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About This Manual 


This manual contains information on installing, configuring, executing, and 
monitoring the Btrieve™ record management system with the NetWare® 
v3.12 operating system. Btrieve is a complete key-indexed record 
management system designed for high-performance data handling and 
improved programming productivity. 


NOTE: Novell would appreciate your comments and suggestions about this 
manual. Once you have become familiar with the manual, please complete the 
User Comments form that appears at the back. You may respond by fax or mail. 


Who Should Read This Manual 


This manual provides information for systems administrators who are 
responsible for maintaining Btrieve databases on a network. This manual is 
also useful to programmers, systems developers, and systems integrators who 
are using Btrieve to develop workstation applications and NetWare Loadable 
Modules™ (NLMs™) for the NetWare operating environment. 


Organization 


+ “Introduction to Btrieve” on page 15 


This chapter discusses Btrieve's client-server design, features, and v6.x 
enhancements. 


+ “Btrieve Architecture” on page 27 


This chapter describes the components of Btrieve and how Btrieve works 
with server and workstation applications. It also provides diagrams that 
illustrate how different applications use different Btrieve components. 
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+ “Installing and Configuring Btrieve” on page 43 


This chapter describes installing, configuring, loading, and unloading 
Btrieve from the server console and from the workstation. It also 
discusses rebuilding existing Btrieve files to take advantage of Btrieve 
v6.x features. The chapter concludes with a discussion of using Btrieve 
with the NetWare Runtime™ serialized NetWare operating system. 


+ “Configuring and Using the Requesters” on page 71 


This chapter provides configuration options and instructions for loading 
and unloading the Btrieve Requester in the DOS, OS/2, and Windows 
environments. 


+ “Using Btrieve Utilities” on page 83 


This chapter describes the utilities available to monitor and maintain your 
database, either from the server console or from workstations on the 
network. 


+ “Description Files” on page 137 


This appendix explains the rules for creating description files, provides a 
description file example, and describes the individual description file 
elements. 


+ “Status Codes and Messages” on page 159 


This appendix lists and explains the Btrieve status codes and messages 
you may encounter while loading or running Btrieve applications. 


+ “Glossary” on page 229 
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Notational Conventions 


Icons 


Typography 





Case 


variable 





This manual uses the conventions described in the following sections to 
present information. 


NOTE: A Note points out an item that may be of interest but is not vital to the 
operation of the product. 


HINT: A Suggestion denotes a hint, a tip, or other information that may be helpful 
but is not critical. 


IMPORTANT: An Important denotes important information that you should read. 


Unless otherwise noted, command syntax, code, and code examples use the 
following conventions: 


Commands and reserved words typically appear in uppercase letters. Unless the 
manual states otherwise, you can enter these items using uppercase, lowercase, or 
both. For example, you can type MYPROG, myprog, or MYprog. 


Square brackets enclose optional information, as in [logName]. If information is not 
enclosed in square brackets, it is required. 


A vertical bar indicates an "either-or" choice of information to enter, as in [filename 
| @filename]. 


Angle brackets enclose multiple choices for a required item, as in <filename | 
@filename>. 


Words appearing in italics are variables that you must replace with appropriate 
values, as in filename. 


An ellipsis following information indicates you can repeat the information more than 
one time, as in [parameter ...]. 
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Associated Documents 


This manual explains how to install Btrieve and use the Btrieve utilities in a 
NetWare environment. For information about developing Btrieve 
applications, refer to the Btrieve Programmer's Manual (available only as part 
of the Btrieve Developer's Kit). 


Registering Your Product 


You are important to us, and it's important for us to know who our customers 
are. Registering your Novell database product enables us to provide you with 
better service and important notifications about your product. Please take a 
moment to complete the pre-addressed NetWare Product Registration Card 
included with this product and return it to us. If you need to contact us by mail, 
telephone, or fax, refer to “Contacting Novell” on page 14. 


Where to Get Help 


Novell offers support through a wide range of programs. This section lists 
sources of help that are available for the Novell Database Products line. 


Telephone Technical Support 


Novell's telephone technical support program provides helpful information 
about getting the best results from your Novell product. Refer to “Contacting 
Novell” on page 14 for information about contacting Novell for technical 
support. If you are contacting Novell for a follow-up on a previous technical 
support issue, please be ready to provide your open call reference number. 


International Technical Support 


International customers may find the Direct Connect SM Fax International 
program useful. This program provides priority handling of fax support, 
which allows international customers to obtain technical support without 
worrying about high telephone costs and time zone differences. Novell 
encourages customers who reside outside the continental United States and 
Canada to contact their local Novell office or Novell authorized reseller for 
more information about international support options. The table on 
“Contacting Novell” on page 14 provides the fax number for international 
technical support. 
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Education and Training 


You can contact the Novell Education department (see “Contacting Novell” 
on page 14) for information about specific courses and training available for 
users of Novell products. 


Product Information 


The Developer Relations group at Novell Austin (see “Contacting Novell” on 
page 14) can provide information about Novell Database Products, technical 
support programs, and the Novell Professional Developers' Program. You can 
request detailed product information from the automated fax system or speak 
to a trained technician about product announcements, pricing, compatibility, 
services, and developer issues. 


Professional Developers’ Program 


The Novell Professional Developers' Program provides programming tools 
and development support for developers who wish to take advantage of the 
features of Novell's software on any of the available platforms (NetWare 
operating system, communications, or database). By enrolling in this program, 
developers gain access to the latest programming tools. For information about 
enrolling, contact Novell Developer Relations (see “Contacting Novell” on 


page 14). 


CompuServe Forum 


You can find information about Novell Database Products under the 
NetWireSM section on CompuServe. NetWire provides 24-hour-a-day 
electronic information services. You can obtain the most recent online 
technical notes, problem reports and fixes, product news, and other helpful 
information. You can also post technical questions and receive answers from 
our technical support staff. 


NOTE: If you already have a CompuServe account, type the following to access 
the NetWire section: 


go novell 


NOTE: For information about subscribing to CompuServe, contact CompuServe, 
Inc. at 1-800-848-8199 (or 1-614-457-0802 in Ohio or outside the U.S. and 
Canada). 
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Contacting Novell 


Novell has established a comprehensive services strategy to support all 
network users and systems—small or large, domestic or international. We 
welcome hearing from you. 


The mailing address for Novell Austin is as follows: 





LI 


Howell, Inc. 

2918 W. Courtyard Drive 

ALetin, Texas 78730-5036 
USA. 





To contact us by telephone or fax, refer to the following table for the 
appropriate number. 





For Telephone Fax 

Technical Support, International 1-800-NETWARE (1-800-638- 1-512-794-1775 

Technical Support, Developer 9273) or 1-801-429-5588 outside 

Relations, or Product Information* the U.S. 

Education Information 1-800-233-EDUC (1-800-233- 1-801-429-3900 
3382) or 1-801-429-5508 outside 
the U.S. 

General Inquiries 1-512-346-8380 1-512-345-7478 


* International customers can contact 
their local reseller for Novell Database 
Products information and their local 
Novell office for information about the 
Professional Developers' Program. 
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Introduction to Btrieve 


The Btrieve key-indexed record management system is designed for high- 
performance data handling and improved programming productivity. Btrieve 
allows your application to retrieve, insert, update, or delete records either by 
key value or by sequential or random access methods. 


Client-Server Design 


Btrieve products include server-based Btrieve (also called NetWare Btrieve™) 
and client-based Btrieve. In most cases, applications written for client-based 
Btrieve can run on server-based Btrieve and vice versa. 


Server-based Btrieve is provided with the NetWare operating system and 
includes the following: 


+ 


Server-based Btrieve Record Manager, which runs at the server and 
manages data I/O with the file system. 


Btrieve communications programs, which handle incoming requests from 
a remote source and which can route requests from a server-based 
application to a copy of the Record Manager running on a remote server. 


Btrieve Requesters, which run at the workstation and handle data I/O 
between the workstation and the server. The Requesters allow 
applications running at the workstation to communicate transparently 
with the Record Manager. Btrieve Requesters are available for DOS, OS/ 
2, Windows, and Unix Ware™ workstations. 


Btrieve utilities, which provide setup, rebuild, monitor, maintenance, and 
recovery programs for Btrieve users and files. 


This manual, which documents using Btrieve in a NetWare environment. 
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Client-based Btrieve is available only as part of a Btrieve Developer's Kit 
(DOS, OS/2, or Windows), which must be purchased separately. Each Btrieve 
Developer's Kit includes the following: 


+ 


+ 


+ 


Client-based Record Manager for the applicable environment (DOS, OS/ 
2, or Windows). The client-based Record Manager executes all 

processing on the workstation. It accesses all files through operating 
system calls. The operating system calls are either executed locally (for 
local files) or redirected to the server (for files on the server). 


Btrieve utilities, which provide setup, rebuild (Btrieve v5.x to v6.x files), 
monitor, maintenance, and recovery programs for Btrieve users and files. 


An installation and operation manual, which documents using Btrieve in 
the applicable environment (DOS, OS/2, or Windows). 


Btrieve Programmer's Manual, which documents the Application 
Programming Interface (APT) and the language interfaces that allow 
Btrieve to be called from various programming languages. 


Btrieve Features 


The following sections introduce some of the features that make Btrieve a 
uniquely powerful record management system. 


Index Maintenance 


Btrieve automatically creates and maintains file indexes as records are 
inserted, updated, and deleted. In addition to automatic index maintenance, 
Btrieve supports the following index features: 


+ 


+ 


+ 


Up to 119 key segments per file 
Adding or dropping any index after a file has been created 


Numerous data types for key values: integer, float, date, 
time, decimal, money, logical, numeric, bfloat, 
string, lstring, zstring, unsigned binary, 
autoincrement, and sign trailing separate 


Numerous key attributes: linked/repeating duplicatable, duplicatable/ 
nonduplicatable, supplemental, modifiable/nonmodifiable, segmented/ 
nonsegmented, descending/ascending sorting, case-sensitive/case- 
insensitive sorting, alternate collating sequence, null (any-segment/all- 
segment)/non-null 
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File Specifications 


Btrieve offers these file specifications: 
+ File sizes up to 4 billion bytes (4 gigabytes) 
+ Number of records limited only by the size limit of the file 


+ Consistent file definition and management routines independent of the 
operating environment 


+ Consistent file structures 


Memory Management 


The cache is an area of memory Btrieve reserves for buffering the pages that 
it reads. When your application requests a record, Btrieve first checks the 
cache to see if the page containing that record is already in memory. If so, 
Btrieve transfers the record from the cache to your application's data buffer. If 
the page is not in the cache, Btrieve reads the page from the disk into a cache 
buffer before transferring the requested record to your application. 


If every cache buffer is full when Btrieve needs to transfer a new page into 
memory, a least-recently-used (LRU) algorithm determines which page in the 
cache Btrieve should overwrite. The LRU algorithm reduces processing time 
by keeping the most recently referenced pages in memory. 


When your application inserts or updates a record, Btrieve first modifies the 
corresponding page in the cache and then writes that page to disk. The 
modified page remains in the cache until the LRU algorithm determines that 
Btrieve can overwrite the image of that page in cache with a new page. 


Generally, a larger cache improves performance because it allows more pages 
to be in memory at a given time. Btrieve allows you to specify the amount of 
memory to reserve for the I/O cache buffers. 


To determine this amount of memory, consider your application's memory 
requirements (if your application is an NLM), the total amount of memory 
installed on your server, and the combined size of all files your application 
will access. 
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Data Integrity 


The following Btrieve features let you support concurrent access while 
ensuring the integrity of your files in a multiuser environment: 


+ 


+ 


Security Controls 


Single-record and multiple-record locks. 


Concurrent and exclusive transactions. (See “Concurrent Transactions” 
on page 23.) 

Deadlock detection (in a server-based environment). 

Shadow paging, which entails making changes to a copy of a page rather 


than to the original page when inserting, updating, or deleting a record. 
(See “Shadow Paging” on page 24.) 


Logging feature, which records (in a log file) any changes made to a 
designated file. 


Roll Forward utility, which uses log files maintained by Btrieve's logging 
feature to recover data corrupted by a system or server failure. 


Btrieve provides the following capabilities for enhancing data security in a 
network environment: 


+ 


+ 


+ 


Assigning owner names to files 
Specifying dynamic encryption and decryption of data 


Providing NetWare file-level security (provided through the Btrieve 
Requesters) 
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Btrieve Enhancements 


Btrieve v6.x provides several new features and performance enhancements 
that support the requirements of today's powerful database management 
systems. The following sections describe these enhancements. 


The first section describes the enhancements that apply only to Btrieve v6.1. 
The second section describes enhancements that apply to Btrieve v6.x (that is, 
to both v6.0 and v6.1). 


Btrieve v6.1 Enhancements 


This section describes enhancements to Btrieve v6.1. 


Support for Operating on a Portion of a Record: Chunks 


Btrieve v6.1 allows you to operate on portions of a record, called chunks, 
rather than on the entire record. This enhancement provides new chunk 
operations that work on any file conforming to the Btrieve v6.x file format. 


New Operations to Support Records Larger than 64 KB 


Through the Get Direct/Chunk (23) and Update Chunk (53) operations, 
Btrieve v6.1 supports records larger than 64 KB. Applications can use chunk 
operations to build records larger than 64 KB in any Btrieve v6.x file that 
allows variable-length records. 


New File Structure to Support Very Long Records 


Btrieve v6.1 also allows an application to create Btrieve files that contain 
structures called Variable-Tail Allocation Tables (VATs). VATs give Btrieve 
faster access to data residing at large offsets in very long records. VATs also 
significantly reduce the buffers sizes Btrieve needs to process records in files 
that use data compression. 


Multiple Alternate Collating Sequences 


Btrieve v6.1 allows you to specify a separate alternate collating sequence 
(ACS) for each key in a file. Btrieve files with multiple keys are no longer 
restricted to having only one ACS. 
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Locale-Sensitive Collating Sequences 


Index Balancing 


Btrieve v6.1 can build an ACS that is sensitive to the specified locale's 
character sorting order. This ability allows Btrieve to sort according to a 
character set specified by a particular country ID and code page. 


When an index page becomes full, Btrieve automatically creates a new index 
page and splits the values in the full page between the two pages. Btrieve v6.1 
now offers the option of using index balancing instead. 


When you use index balancing, Btrieve looks for available space in other 
index pages associated with the same key each time an index page becomes 
full. Btrieve then rotates values from the full page into the pages that have 
space available. Index balancing increases index page utilization, results in 
fewer pages, and produces an even distribution of keys among nodes on the 
same level. 


Performing Reads While Creating an Index 


New Data Type 


With Btrieve v6.1, you can perform reads while a Create Index (13) operation 
is executing. Previous versions of Btrieve locked the entire file when 
executing a Create Index operation. 


Btrieve v6.1 allows you to specify a new data type for keys called sign 
trailing separate (STS). STS is a COBOL data type. Basically a 
numeric data type, it is represented as an ASCII string that is right-justified 
and padded with zeros. 


Percentage Operations 


Btrieve v6.1 provides two new operations that a window-oriented application 
can use for implementing scroll bars: 


+ The Find Percentage (45) operation finds either a record's physical 
location within a file, or the record's position relative to a key path. The 
location or position is expressed as a percentage value. 


+ The Get By Percentage (44) operation retrieves a record by that record's 
position in the Btrieve file, where the position is based on a percentage 
value you supply when you call the operation. You can specify whether 
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the position is relative to a specified key path or represents the record's 
actual physical location in the file. 


No Currency Change Option 


Btrieve v6.1 provides a No Currency Change option on inserts and updates. In 
previous versions of Btrieve, positioning was reestablished based on the key 
value of the inserted or updated record. 


New Ability to Specify Repeating- or Linked-Duplicatable Keys on Create Operations 


On the Create (14) and Create Index (31) operations, Btrieve v6.1 allows you 
to specify a key as either a repeating-duplicatable key or a linked-duplicatable 
key. 


Improved Btrieve Requesters 


The Btrieve DOS and OS/2 Requesters now support MAP ROOT drives and 
NetWare file-level security. Since the Windows Requester requires the DOS 
Requester, Windows users can also take advantage of these features. When 
opening files in a NetWare v3.12 environment, Btrieve Requesters provide 
enhanced performance by reducing the bindery access for each file and 
reducing network traffic in general. 


The Btrieve v6.1 Requesters have three new features: 
+ Automatic support for double-byte character environments 
¢ Support for the NetWare Runtime serialized NetWare operating system 
+ Optional compression of data prior to network transmission 


NOTE: Btrieve now provides a requester for the UnixWare environment. For 
information about this new UnixWare Requester, please refer to the Readme file 
that accompanies this release. 
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Btrieve 6.x Enhancements 


New File Format 


Online Backups 


This section describes ehancements that apply to Btrieve v6.x (that is, v6.0 
and v6.1). 


When creating files, Btrieve v6.x uses a new file format that allows faster data 
access than was possible with previous Btrieve versions. This format, 

introduced in Btrieve v6.0 and modified slightly in Btrieve v6.1, is responsible 
for many of the enhancements and new features available with these releases. 


Btrieve v6.0 operates on any file created with Btrieve v6.1 unless that file uses 
v6.1 features that have altered the Btrieve file format (such as multiple ACSs 
and VATs). 


Btrieve versions earlier than v6.x cannot open files that have a v6.x format. 
However, Btrieve v6.x can open files created with earlier versions of Btrieve. 
When Btrieve v6.x opens files from earlier versions, it does not convert the 
files to the v6.x file format. 


The Create Btrieve Files in Pre v6.x Format configuration optionis useful if 
you must use newly created files with versions of Btrieve earlier than v6.0. 


Through a feature called continuous operation, Btrieve v6.x now lets you back 
up Btrieve files while they are open and in use. This feature is important for 
applications that conduct transactions 24 hours a day. 


When you enable the continuous operation feature, Btrieve opens each 
original file in read-only, shareable mode to allow backup utilities to access 
the file's static image. 


Any changes to the original file that occur during the backup are stored in a 
temporary file called a delta file. When the backup ends, Btrieve 
automatically updates the original file with the changes from the delta file and 
then deletes the temporary delta file. 
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Concurrent Transactions 


Versions of Btrieve earlier than v6.0 support only one type of transaction: 
exclusive. When an application reads, updates, inserts, or deletes a record from 
a file in an exclusive transaction, Btrieve locks the entire file for the duration 
of the transaction. This type of locking is known as file-level transaction 
locking. 


Once a file is locked in an exclusive transaction, other users can still read the 
file, provided they are not involved in exclusive transactions and are not 
attempting to lock the file themselves. They cannot, however, make any 
changes to the file. 


If the file uses a Btrieve v6.x format, other users will not see changes that 
occur during the transaction until that transaction ends. (If the file uses the 
format of versions of Btrieve earlier than v6.x, other users can see such 
changes.) 


In addition to supporting exclusive transactions, Btrieve v6.x supports a new 
type of transaction: concurrent. Concurrent transactions allow one or more 
applications to run multiple transactions simultaneously for the same Btrieve 
file (if the file uses the Btrieve v6.x format). 


When a Btrieve v6.x file is included in a concurrent transaction, modifications 
cause Btrieve to lock only the page (or pages, if the record is variable length) 
that contains the record, as well as its associated index pages. 


This allows other users to modify or include the same file in their own 
concurrent transaction, as long as no concurrent transaction has already locked 
the pages that contain the records to be modified (or any affected index pages). 


Concurrent transactions have the following additional features: 
+ Locked pages remain locked for the duration of the transaction. 


¢ If the transaction simply reads a record, Btrieve does not lock the 
corresponding page (unless a read lock is applied). 


+ Other users can read the data on the locked pages, but they cannot lock 
the pages (by updating or applying an explicit read lock). 


+ Other users cannot see the changes to a file in a transaction until the 
transaction ends. (That way, if a system failure occurs before the 
transaction completes, other users will not have read false data—that is, 
data that will be rolled back.) 
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NOTE: For compatibility, Btrieve v6.x supports exclusive transactions, but with 
one difference from previous versions: if the exclusive transaction affects Btrieve 
v6.x files, other users cannot see the changes to those files until the transaction 
ends. 


Shadow Paging 


With Btrieve file versions earlier than v6.0, Btrieve uses pre-imaging to 
protect files from corruption in case ofa system failure. Before updating a file, 
Btrieve creates a temporary pre-image file. This file contains the pages to be 
updated from the original file. Btrieve then performs the update on the original 
file. If the system fails during the update, Btrieve can restore the original file 
using the pre-image file. 


A new Btrieve v6.x page handling technique called shadow paging has 
replaced pre-imaging. When a user needs to change a page (either inside or 
outside a transaction), Btrieve creates a shadow page—a virtual copy of the 
original page within the same Btrieve file. Btrieve then makes the changes to 
the shadow page instead of to the original. 


When the changes are committed (either when the operation is complete or the 
transaction ends), Btrieve designates the shadow page as the current page, and 
the original page becomes available for reuse. If a system failure occurs before 
the changes are committed, Btrieve drops the shadow page, and the current 
page remains in its original condition. 


With shadow paging, each user works with a virtual copy of the page. 
Consequently, two users can access the same logical page, and neither user 
sees the other user's changes until the operation or transaction is complete. 
Also, shadow paging enhances reliability because the original file is always 
valid and internally consistent. 


New Caching Algorithm 


Btrieve v6.x provides new caching algorithms that improve memory 
management for concurrent users. These new algorithms include hashing 
search methods for improved access, concurrent sharing of a single cache, and 
use of an existing cache across operations. 
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Better Usage of Large Data File 


Btrieve v6.x provides faster access to and more efficient use of large data files. 
With Btrieve v6.x, you can create additional indexes for large data files more 
quickly than in previous versions, and new merge sorts take advantage of 
whatever cache is available. 


Up to 119 Key Segments 


Btrieve v6.x supports up to 119 key segments in files with a page size of 4,096 
bytes. The maximum number of key segments you can define for a file 
depends on the file's page size. Versions of Btrieve earlier than v6.0 supported 
a maximum of 24 key segments. 


Adding and Dropping Any Index 


Btrieve v6.x supports adding and dropping any index. (In versions of Btrieve 
earlier than v6.0, you could add and drop only supplemental indexes.) Also, 
you can drop indexes without renumbering the remaining indexes. 


Specific Key Numbers Allowed When Creating a File or Index 


Btrieve v6.x allows an application to assign specific key numbers when 
creating a v6.x format file with indexes, or when creating an index for a 
preexisting v6.x file. 


Optional Renumbering of Keys 


With Btrieve v6.x, the Drop Index (32) operation allows an application to 
specify whether to renumber the remaining keys when dropping an index from 
a Btrieve file. (The file must use the Btrieve v6.x format.) 


Enhanced Support for Case-Insensitive Keys 


With Btrieve v6.x, you can create case-insensitive keys without using an 
alternate collating sequence. When creating a file, you can use the key 
specifications to specify case-insensitive keys. With case-insensitive keys, the 
letter a is sorted the same as the letter A. 


Introduction to Btrieve 25 


Enhancement to autoincrement Key 


In Btrieve v6.x, you can initialize the value of a field in every record of a file 
to zero and later add an index of type autoincrement. This feature allows 
you to prepare for an autoincrement key without actually building the 
index until you need it. 


Reserved Space for Duplicate Pointers 


Btrieve v6.x allows reserving duplicate pointers on data records for linked 
duplicate keys. When creating a Btrieve v6.x file, an application can reserve 
space in the data records for extra, unused duplicate pointers. Later, when an 
application adds an index that allows duplicate values, Btrieve stores pointers 
to those duplicate values in the reserved space (unless the Repeating 
Duplicates key attribute has been specified). 


Key-Only File Modification 


New Stat Option 


With Btrieve v6.x, you can update and delete records in key-only files. In 
versions of Btrieve prior to v6.0, you could only insert records. 


A new option in the Stat (15) operation allows an application to obtain 
additional information such as a file's Btrieve version and the number of 
unused duplicate pointers. This feature also works with files created with 
previous versions of Btrieve. 


Locking in Extended Operations 


Unlike previous versions of Btrieve, v6.x allows an application to use locks 
on the extended operations: Get Next Extended (36), Get Previous Extended 
(37), Step Next Extended (38), and Step Previous Extended (39). 


Support for Referential Integrity 


Btrieve v6.x supports the use of referential integrity (RI) constraints created 
through Novell's NetWare SQL™ relational data access system. RI ensures 
that dependent data stays synchronized throughout the database. No Btrieve 
operations currently exist to manipulate RI constraints directly; you must use 
NetWare SQL. 
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Btrieve Architecture 


If you are new to Btrieve, you should read this chapter before installing and 

configuring Btrieve. It provides an introduction to the Btrieve components and 
how they work with Btrieve applications. If you have used Btrieve before, you 
may want to skip to the example diagrams of Btrieve architecture, which begin 


in “Examples of Btrieve Architecture” on page 35. 
This chapter discusses the following topics: 
+ “Components of Btrieve” on page 27 
+ “Btrieve Applications on a Server” on page 31 
+ “Btrieve Applications on a Workstation” on page 33 


+ “Examples of Btrieve Architecture” on page 35 


Components of Btrieve 


The major components of server-based Btrieve are as follows: 
+ “Server-Based Record Manager” on page 28 
+ “Communications Programs” on page 28 
+ “Workstation Requesters” on page 30 


+ “Btrieve Utilities” on page 30 
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Server-Based Record Manager 


Btrieve's server-based Record Manager (BTRIEVE.NLM) must be loaded at 
every server that accesses Btrieve files. The Btrieve NLM consists of a library 
of Btrieve functions and handles these tasks: 


+ Performs disk I/O for Btrieve files at the server where it resides 
¢ Provides concurrency and integrity controls on the server where it resides 


+ Logs all Btrieve requests that result in changes to a file (if logging is 
enabled for that file) 


Communications Programs 


Btrieve provides the following communications programs: 
+ Btrieve Message Router (BROUTER.NLM) 
+ BSPXCOM.NLM 
+ BSPXSTUB.NLM 
+ RSPXSTUB.NLM 


Btrieve Message Router 


The Btrieve Message Router (BROUTER.NLM) handles outgoing requests 
from your server to a remote server. The Message Router allows a Btrieve 
application running as an NLM on the server to communicate with remote 
servers on which other Btrieve NLMs are loaded. Also, the Message Router 
maintains transaction concurrency controls during transactions involving 
Btrieve files on more than one server. 


If your server-based application needs to access files on another server, you 
must have the Message Router loaded on your server. When you request files 
from another server, the Message Router sends that request to BSPXCOM 
(discussed in the next section) on the remote server. BSPXCOM routes your 
request to the Btrieve NLM on that server and then sends the response back to 
the Message Router on your server. 
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BSPXCOM 


BSPXCOM handles incoming requests to the Btrieve NLM from a remote 
source. The remote source could be a Requester at a workstation or the 
Message Router on another server. BSPXCOM must be loaded on servers that 
support remote requests. 


If no workstations or other servers make requests to the Btrieve NLM, you 
may not want to have BSPXCOM loaded at your server. For example, assume 
your Btrieve NLM receives calls only from other NLMs running at your 
server. In this case, you could choose not to load BSPXCOM for security 
reasons. (Not loading BSPXCOM allows you to restrict applications other 
than the ones on your server from accessing your Btrieve files.) 


BSPXSTUB and RSPXSTUB 


If you do not load BSPXCOM and want to use the Btrieve Monitor utility, you 
must load either the BSPXSTUB or RSPXSTUB communications module. 
These modules resolve external references for the Monitor utility that 
BSPXCOM would otherwise resolve. 


Use the following guidelines to determine whether you need BSPXSTUB or 
RSPXSTUB: 


¢ If you want to use the Btrieve Monitor utility but do not want to load 
BSPXCOM, and the NLMs on the server are accessing Btrieve files only 
on the local server, load BSPXSTUB at the server. 


¢ If you want to use the Btrieve Monitor utility to monitor outgoing 
requests generated by the Message Router to another server and you do 
not want to load BSPXCOM, load RSPXSTUB instead of BSPXSTUB at 
the server. 


NOTE: The Btrieve Monitor utility's Communication Statistics option (discussed in 
“Using Btrieve Utilities” on page 83) displays SPX communication statistics. The 
communications module you load affects the statistics displayed. For example, if 
you load BSPXCOM, you see incoming and outgoing SPX statistics for 
BSPXCOM. If you load BSPXSTUB, you see all zeros. If you load RSPXSTUB, 
you see incoming and outgoing SPX communication statistics from the Message 
Router. 
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Workstation Requesters 


Btrieve provides the following Requesters for applications running on the 
workstation: 


+ BREQUEST.EXE—DOS Requester 
+ BTRCALLS.DLL—OS/2 Requester 
+ WBTRCALL.DLL—Windows Requester 


NOTE: Btrieve now provides a requester for the UnixWare environment. For 
information about this new UnixWare Requester, please refer to the Readme file 
that accompanies this release. 


A Btrieve Requester must be loaded at each workstation that makes Btrieve 
requests. The Requester receives Btrieve requests from an application and 
relays them via BSPXCOM to the Btrieve NLM running on the server. After 
the Btrieve NLM processes the request, BSPXCOM sends the results back to 
the Requester, which forwards them to the application. 


For information on starting the Requester in each operating environment, refer 
to “Configuring and Using the Requesters” on page 71. 


Btrieve Utilities 


Btrieve provides the following utilities for Btrieve file management: 


+ Setup and Rebuild utilities (BSETUP.NLM and BREBUILD.NLM)— 
You can use the Setup utility to change the settings of Btrieve 
configuration options, and you can use the Rebuild utility to convert 
existing Btrieve v5.x files to Btrieve v6.x format. (As “Rebuilding 
Existing Btrieve Files” on page 57 explains, you can choose to run the 
Rebuild utility from within the Setup utility.) 


+ Monitor utility (BTRMON.NLM)—You can use this utility to monitor 
the activity of Btrieve at the server. 


+ Maintenance utility (BUTIL.NLM)—You can use this utility to import 
and export Btrieve data and transfer data from one Btrieve file to another. 
This utility also lets you enable and disable continuous operation on your 
Btrieve files. 
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+ Roll Forward utilities (BROLLFWD.EXE for DOS, PBROLL.EXE for 
OS/2, and WBROLL.EXE for Windows)—The Roll Forward utilities 
recover changes made to a Btrieve file between the time of the last backup 
and a system failure. The Roll Forward utilities are for workstation use 
only. 


For more information about the Btrieve Setup and Rebuild utilities, refer to 
“Installing and Configuring Btrieve” on page 43. For information about the 
Btrieve Monitor, Maintenance, and Roll Forward utilities, refer to “Using 
Btrieve Utilities” on page 83. 


Btrieve Applications on a Server 


A Btrieve application running on a server (that is, an NLM) can access data on 
the local server or on a remote server, as follows: 


+ Accessing Local Data—The application makes a request for Btrieve data 
located on the local server. The Btrieve NLM processes the request on the 
server where the Btrieve request originated. 


+ Accessing Remote Data—The application makes a request for Btrieve 
data located on a remote server. The Btrieve NLM processes the request 
on the remote server. 


The following sections describe the events that occur when your NLM 
application makes local and remote requests. 


Server Application Accessing Local Data 


When an application running on a server is accessing data on that server, the 
Btrieve NLM must be loaded on that server. The following steps describe 
accessing data on the local server: 


1. The application sends a request to the Btrieve NLM. If the Message 
Router is not loaded, the call goes directly to the exported entry point of 
Btrieve on the local server. 


If the Message Router is loaded, it relays the call to Btrieve on the local 
server. 


2. Btrieve processes the request using the Btrieve library of function calls. 
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3. 


If the Message Router is not loaded, Btrieve returns the appropriate data 
and status code directly to the calling application. 


If the Message Router is loaded, Btrieve returns the data and status code 
to the Message Router. The Message Router then transports the data and 
status code to the calling application. 


Server Application Accessing Remote Data 


When an application running on a local server is accessing data on a remote 

server, the Message Router and the Btrieve NLM must be loaded on the local 
server, and BSPXCOM and the Btrieve NLM must be loaded on the remote 

server. The following steps describe accessing data on a remote server: 


l. 


The application (running on the local server) makes a request to access a 
Btrieve file located on a remote server. 


. The Message Router on the local server detects that the request is for a 


remote Btrieve file and sends the request to BSPXCOM on the remote 
server. 


. BSPXCOM (remote) relays the request to the Btrieve NLM (remote) by 


making Btrieve function calls. 


. The Btrieve NLM (remote) returns the appropriate data and status code to 


BSPXCOM (remote). 


. BSPXCOM (remote) returns the data and status code to the local server, 


where the Btrieve request originated. 


. The Message Router (local) returns the results to the calling application 


(local). The Message Router places the results in the application's 
memory at the location designated by the parameters passed to Btrieve in 
the function call. Control then returns to the calling application. 
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Btrieve Applications on a Workstation 


A Btrieve application running on a workstation can access local, remote, or 
local and remote data as follows: 


+ Accessing Local Data—The application makes a request for Btrieve data 
located on the workstation. Client-based Btrieve processes the request on 
the same workstation where the request originated. 


+ Accessing Remote Data—The application makes a request for Btrieve 
data located on a remote server. The request is sent to the Requester, 
which passes the request to the Btrieve NLM on the remote server. The 
Btrieve NLM processes the request. 


+ Accessing Local and Remote Data—The application makes a request for 
Btrieve data located on the local workstation or a remote server. The 
Requester intercepts the request for data. The Requester then determines 
whether the data is on the workstation or a remote server and routes the 
appropriate request to client-based Btrieve on the workstation or the 
Btrieve NLM on a remote server. 


The following sections explain what happens when your workstation 
application makes local and remote requests. 


Workstation Application Accessing Local Data 


When an application is accessing local data on the workstation, client-based 
Btrieve must be loaded on the workstation. The following steps describe 
accessing data on the workstation: 


1. The application makes a Btrieve request using a function call. 


2. The interface code that you link with your application makes the call to 
client-based Btrieve. (Novell provides the interface code.) 


NOTE: In a Windows or OS/2 environment, you must import the function definition. 


3. Client-based Btrieve processes the request using the Btrieve library of 
function calls. 


4. Client-based Btrieve returns the appropriate data and status code directly 
to the calling application. 
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Workstation Application Accessing Remote Data 


When an application is accessing data on a remote server from a workstation, 
the Requester must be loaded on the workstation, and BSPXCOM and the 
Btrieve NLM must be loaded on the server. The following steps describe 
accessing data on a server from an application running on the workstation: 


1. The application makes a Btrieve request using a function call. 


2. The interface code that you link with your application makes the call to 
the Requester. (Novell provides the interface code.) 


NOTE: In a Windows or OS/2 environment, you must import the function definition. 


3. The Requester packages the request into a network message and routes 
the message to BSPXCOM on the remote server. 


4. BSPXCOM receives the network message, validates the parameters, and 
then executes the request by making function calls to the Btrieve NLM. 


5. The Btrieve NLM processes the request and returns the results to 
BSPXCOM. 


6. BSPXCOM forwards the results to the Requester at the workstation. 


7. The Requester returns the appropriate data and status code to the 
parameter variables in your application's memory and returns control to 
your application. 


Workstation Application Accessing Local and Remote Data 


When an application is accessing local and remote data from a workstation, 
the Requester and client-based Btrieve must be loaded on the workstation, and 
BSPXCOM and NetWare Btrieve must be loaded on the server. The following 
steps describe accessing local and remote data from an application running on 
the workstation: 


1. The application makes a Btrieve request using a function call. 


2. The interface code that you link with your application makes the call to 
the Requester. (Novell provides the interface code.) 


NOTE: In a Windows or OS/2 environment, you must import the function definition. 


3. The Requester determines whether the server or the workstation should 
receive the request. 
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4. 


This step varies, depending on whether the requested data is on the 
workstation or on a remote server: 


+ If the requested data is on the workstation, the Requester sends the 
request directly to client-based Btrieve. Btrieve processes the request 
using the Btrieve library of function calls. Client-based Btrieve 
returns the appropriate data and status code directly to the calling 
application. 


+ If the requested data is on a remote server, the Requester packages 
the request into a network message and routes the message to 
BSPXCOM on that server. BSPXCOM receives the network 
message, validates the parameters, and then executes the request by 
making function calls to the Btrieve NLM. 


The Btrieve NLM processes the request and returns the results to 
BSPXCOM. BSPXCOM forwards the results to the Requester at the 
workstation. The Requester returns the data and status code to the 
calling application. 


Examples of Btrieve Architecture 


The diagrams in this section demonstrate how different Btrieve applications 
require different Btrieve components. This section discusses the following 
examples: 


+ 


+ 


+ 


“Server Application Using the Btrieve NLM” on page 36 
“Server Application Using the Btrieve Message Router” on page 37 


“Server Application Using the Btrieve Message Router and BSPXCOM” 
on page 38 


“Workstation Application Using the Requester and Client-Based Btrieve” 
on page 39 


“Server Application Using RSPXSTUB” on page 40 
“Server Application Using BSPXSTUB” on page 41 
“Server Application Using NetWare SQL” on page 42 


NOTE: The following examples indicate remote requests with dashed lines and 
local requests with solid lines. 
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Server Application Using the Btrieve NLM 


Figure 1 shows an application accessing Btrieve data on the local server. The 
application is making local requests to the local Btrieve NLM. Note that 
BSPXCOM is not loaded because there are no incoming requests to the 
Btrieve NLM from another server or workstation. 


Figure 1 Server Application Using the Btrieve NLM 
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Server Application Using the Btrieve Message Router 


Figure 2 shows an application running on Server A. It is making requests to 
the local Btrieve NLM (Server A) and to a remote Btrieve NLM (Server B) 
via the Btrieve Message Router. 


The Message Router handles outgoing requests from Server A to the remote 
Server B. The Message Router must be loaded on Server A in order to send 
the requests to Server B. BSPXCOM must be loaded on Server B to accept 

incoming requests from the Message Router. 


Figure 2 Server Application Using the Btrieve Message Router 
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Server Application Using the Btrieve Message Router and BSPXCOM 


Figure 3 illustrates a server application that requires both the Btrieve Message 
Router and BSPXCOM. 


In Figure 3, the Message Router handles outgoing requests from the local 
server to a remote server. BSPXCOM handles incoming requests to the 
Btrieve NLM from a remote source (either a Requester at a workstation or the 
Message Router on another server). The server is supporting incoming 
requests from a remote source and outgoing requests to a remote server. 


Figure 3 Server Application Using the Btrieve Message Router and BSPXCOM 
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Workstation Application Using the Requester and Client-Based 
Btrieve 


Figure 4 shows an application running on a workstation. The application is 
accessing local data via client-based Btrieve and remote data via the 
Requester. The Requester passes requests for local data to client-based 
Btrieve. 


In this environment, the Requester on the workstation performs the same 
function as the Message Router in Figure 3 on page 38. BSPXCOM handles 
incoming requests to the Btrieve NLM from a remote source. 


Figure 4 Workstation Application Using the Requester and Client-Based Btrieve 
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Server Application Using RSPXSTUB 


Figure 5 shows an application running on Server A. It is accessing both local 
and remote data. The Btrieve Monitor utility (BTRMON.NLM) is also 
running on Server A. To run the Monitor utility, Server A must have either 
BSPXCOM, BSPXSTUB, or RSPXSTUB loaded. 


Since the Btrieve NLM on Server A is not accepting any incoming requests 
from workstations or remote servers, BSPXCOM is not loaded. Instead, 
RSPXSTUB is loaded on Server A; it allows users to see the Btrieve Message 
Router's communication statistics through the Monitor utility's 
Communication Statistics option. 


Figure 5 Server Application Using RSPXSTUB 
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Server Application Using BSPXSTUB 


Figure 6 shows an application running on the server. The application is 
accessing local data. The Btrieve Monitor utility (BTRMON.NLM) is also 
running on the server. Since the Btrieve NLM is not accepting any incoming 
requests, BSPXCOM is not loaded. However, to run the Monitor utility, the 
server must have either BSPXCOM, BSPXSTUB, or RSPXSTUB loaded. 
Since the Btrieve Message Router is not loaded, BSPXSTUB is the 
appropriate communications module to have loaded. 


NOTE: When BSPXSTUB is loaded, the Communication Statistics option in the 
Btrieve Monitor utility shows zeros for the SPX statistics, since there is no SPX 
activity. 


Figure 6 Server Application Using BSPXSTUB 
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Server Application Using NetWare SQL 


Figure 7 shows NetWare SQL running on Server A. Since NetWare SQL 
needs to access data on both Server A and Server B, the Btrieve Message 
Router is loaded on Server A. In addition, NSSPXCOM is loaded on Server A 
because NetWare SQL is also responding to requests from a NetWare SQL 
Requester running on a remote workstation. (NSSPXCOM provides the same 
functionality for NetWare SQL as BSPXCOM provides for Btrieve.) 


Figure 7 Server Application Using NetWare SQL 
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Installing and Configuring Btrieve 


This chapter describes how to install and configure Btrieve. It discusses the 
following topics: 


+ 


+ 


+ 


+ 


+ 


“Installing Btrieve” on page 43 

“Configuring Btrieve” on page 45 

“Starting and Stopping Btrieve” on page 55 
“Rebuilding Existing Btrieve Files” on page 57 
“Using Btrieve with NetWare Runtime” on page 67 


Installing Btrieve 


The following sections discuss the system requirements and the installation 
procedure for Btrieve v6.1. 


System Requirements 


Make sure your system has the following: 


+ NetWare v3.12 


NOTE: Running Btrieve v6.1 in a NetWare v3.12 environment requires 
AFTER311.NLM, which Btrieve loads automatically. 


+ Adequate memory at the server to load the Btrieve NLM (approximately 


528 KB) and the appropriate communications modules 


NOTE: The memory required for the communications modules varies, depending 
on the values you specify for the Largest Record Size and Number of Remote 
Sessions configuration options. 


Installing and Configuring Btrieve 43 


+ Adequate memory for the Btrieve Requester at each workstation. 
Memory requirements vary, depending on the parameters you specify 
when you load the Requester. These are the default parameters: 


+ The DOS Requester requires approximately 29 KB. 
+ The OS/2 Requester requires approximately 40 KB. 


+ The Windows Requester requires approximately 30 KB. (To use the 
Windows Requester, you must also have the DOS Requester loaded.) 
NOTE: Btrieve also provides a requester for the UnixWare environment. For 


information about this new UnixWare Requester, please refer to the Readme 
file that accompanies this release. 


Using the NetWare INSTALL Utility 


The NetWare INSTALL utility lets you load Btrieve automatically at the 
server. For more information about the NetWare INSTALL utility, refer to 
your NetWare documentation. 


After loading Btrieve with the INSTALL utility, you can configure Btrieve 
according to your Btrieve application's requirements. Use the guidelines 
discussed in the next section, "Configuring Btrieve." You can then activate 
Btrieve as discussed in “Starting and Stopping Btrieve” on page 55. 
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Configuring Btrieve 


Table 1 





Configuration Option 


You can configure Btrieve by setting configuration options. When you load 
Btrieve with the INSTALL utility, these options are set to their default values. 
(Table 1 shows the default values.) However, your Btrieve application may 
require different values for these options. 


NOTE: To determine which values your application requires, refer to the 
documentation included with that application. 


Default Values for Configuration Options 


Default Value 





“Number of Open Files” on page 46 20 files 
“Number of Handles” on page 46 60 handles 
“Number of Locks” on page 47 20 per client 
“Number of Transactions” on page 47 15 transactions 
“Largest Compressed Record Size” on page 47 0 bytes 
“Largest Record Size” on page 48 8,192 bytes 
“Largest Page Size” on page 49 4,096 bytes 
“Number of Remote Sessions” on page 49 15 sessions 
“Cache Allocation” on page 49 256 KB 
“Perform Index Balancing” on page 50 No 

“Logging of Selected Files” on page 50 No 

“Create Btrieve Files in Pre v6.x Format” on page 51 No 

“Create Files as Transactional” on page 51 No 
“Configure BSTART.NCF to Load BROUTER” on page 51 No 





The following section discusses each configuration option individually. You 
can change the values for the configuration options by running the Btrieve 
Setup utility (as described on “Running the Setup Utility” on page 52). The 
Setup utility stores your changes in the BSTART.NCF NetWare command file. 
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After configuring Btrieve, you can activate Btrieve as described in “Starting 
and Stopping Btrieve” on page 55. 


Configuration Options 


This section lists the Btrieve configuration options in the order in which they 
appear in the Setup utility. For each option, the discussion includes the 
following: 


+ Range of acceptable values 
+ Default value 
+ Approximate memory required 


¢ Description of the option 


Number of Open Files 
Range: 1 through 64,000 files 
Default: 20 files 
Approximate Memory Required: 425 bytes per file 


This option specifies the maximum number of unique Btrieve files that can be 
open at one time at the server. The value you specify determines the size of the 
internal tables used to track active files. Each unique Btrieve file on the server 
counts as one file. 


Number of Handles 
Range: 1 through 64,000 file handles 
Default: 60 handles 
Approximate Memory Required: 200 bytes per handle 


This option specifies the maximum number of file handles that the Btrieve 
NLM can use at one time. 


NOTE: Keep in mind that the number of handles is different from the number of 
open files. That is, if two sessions open the same file on the same server, Btrieve 
counts it as one open file, but two different file handles. See “Number of Locks” on 
page 47 (next) for a definition of sessions. 
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Number of Locks 
Range: 0 through 64,000 locks 
Default: 20 locks per client session 
Approximate Memory Required: 20 bytes per lock 


This option sets the maximum number of records a client session can lock at 
the server at one time. (A session occurs when a client uses the Btrieve 
Requester or Message Router to communicate with the Btrieve NLM, or when 
an NLM application calls Btrieve directly.) 


This maximum applies to whichever type of read lock (single record or 
multiple record) the client session is using. Single-record locks allow an 
application to lock only one record at a time. Multiple-record locks allow an 
application to lock more than one record at a time. 

Number of Transactions 
Range: 0 through 64,000 transactions 
Default: 15 transactions 


Approximate Memory Required: 20 bytes + (2 * maximum number of files) 


This option sets the maximum number of Btrieve clients that can 
simultaneously have active transactions at the server. (Each of these clients 
can have only one active transaction at the server.) 


For example, if you specify 6 transactions, Btrieve creates a transaction file at 
the server (BTRIEVE.TRN in the SYS:SYSTEM directory) and allows a 
maximum of 6 clients to have one active transaction each at the server. If you 
specify a value of 0, no clients can perform a Btrieve transaction. 

Largest Compressed Record Size 
Range: 0 through 64 KB 
Default: 0 KB 
Approximate Memory Required: 2,048 bytes * specified value 


This option allows you to allocate memory for a compression buffer that 
Btrieve can use when you access records in a Btrieve file created with the Data 
Compression file attribute enabled. Btrieve allocates a compression buffer 
with a size of 2,048 bytes multiplied by the value you specify for this option. 
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Use the following guidelines when specifying the value for this option: 


+ If you use compressed Btrieve files, determine the size (in bytes) of the 
largest record in any of your compressed files. Round the record size to 
the next whole kilobyte. For example, if the largest record you need to 
access is 1,800 bytes, specify 2 for this option. Btrieve will allocate 4,096 
bytes (that is, 2,048 * 2) of memory for the compression buffer. 


+ If every compressed file you use has Variable-tail Allocation Tables 
(VATs), set this option to the file's largest page size (in bytes) divided by 
128. For example, if the largest page size is 1,024 bytes, specify 8 for this 
option. Btrieve will allocate 16,384 bytes (that is, 2,048 * 8) of memory 
for the compression buffer. 


+ Ifyou do not use compressed files, set this value to 0. You cannot improve 
performance, and may waste memory, by specifying a value higher than 
you need. 


Largest Record Size 
Range: 600 through 64,000 bytes 
Default: 8,192 bytes 


Approximate Memory Required: recordLength * (remoteSessions / 
5) + 1+ (remoteSessions * recordLength / 580) * 600 
recordLength Largest record size + 538 bytes remoteSessions 
Number of remote sessions 


This option specifies the length of the largest record or record chunk that any 
remote Btrieve application (excluding other NLMs that call Btrieve, such as 
NetWare SQL) can access at the server. A record chunk is any arbitrary 
portion of a record, specified by its offset and length. 


Specify the length of the record (or record chunk) in bytes. Specifying a value 
higher than you need does not improve performance and may waste memory. 


NOTE: For applications running on workstations, the maximum record length is 
57,000 for the DOS Requester, 65,000 for the OS/2 Requester, and 57,000 for the 
Windows Requester. 
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Largest Page Size 


Range: 512 through 4,096 bytes 
Default: 4,096 bytes 
Approximate Memory Required: Not applicable 


This option specifies the maximum page size (in bytes) of any Btrieve file you 
want to access. The page size must be a multiple of 512 bytes, but no greater 
than 4,096 bytes. 


Setting the page size to 512, 1,024, 2,048, or 4,096 can improve performance 
because these page sizes correspond to disk block sizes. If you set the page 
size to 1,536, 2,560, 3,072, or 3,584, a given disk read may span two disk 
blocks and therefore require two disk accesses per page. 


Number of Remote Sessions 


Cache Allocation 


Range: | through 64,000 sessions 
Default: 15 sessions 
Approximate Memory Required: 150 bytes * number of remote sessions 


This option specifies the maximum number of SPX sessions that can access 
the remote Btrieve NLM at one time. (A session occurs when a client uses the 
Btrieve Requester or the Message Router to communicate with the remote 
Btrieve NLM.) Each session is allocated two packet buffers for Btrieve 
requests. 


NOTE: If you receive a Status Code 96, increase the value for this option. 
However, do not specify a value higher than you need. Specifying a value that is 
too high does not improve performance; instead, it uses memory that NetWare or 
other processes might need. 


Range: 32 through 64,000 KB 
Default: 256 KB 
Approximate Memory Required: Not applicable 


This option specifies the size of the cache (in kilobytes) that Btrieve allocates. 
To achieve best performance, allocate a cache size equal to the sum of the sizes 
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of the files you are using. However, be careful not to take all available cache, 
especially if the server is running other applications. 


You cannot improve performance, and may waste memory, by specifying a 
value higher than you need. 


Perform Index Balancing 
Range: Yes or No 
Default: No 
Approximate Memory Required: Not applicable 


When an index page becomes full, Btrieve automatically creates a new index 
page and splits the values in the full index page between the two index pages. 
The Perform Index Balancing option lets you avoid creating a new index page 
every time an old one fills up. 


If you specify Yes for this option, Btrieve looks for available space in sibling 
index pages each time an index page becomes full. Btrieve then rotates values 
from the full index page into the pages that have space available. 


Index balancing increases index page utilization, results in fewer index pages, 
and produces an even distribution of keys among nodes on the same level, thus 
increasing performance during Get operations. However, when you specify 

Yes for this option, Btrieve requires extra time to examine more index pages 
and may require more disk I/O during Insert, Update, and Delete operations. 


NOTE: You can also specify index balancing on a file-by-file basis by setting a bit 
in the file flag's word when the file is created. If you specify Yes to the “Perform 
Index Balancing” on page 50 option, Btrieve performs index balancing on every file 
regardless of the balanced file flag specification. 


Logging of Selected Files 
Range: Yes or No 
Default: No 
Approximate Memory Required: Not applicable 


This option controls whether Btrieve logs operations executed on selected 
files. If you specify Yes, Btrieve logs all operations that change any file listed 
in the BLOG.CFG file on Btrieve's server volume. If you specify No, Btrieve 
performs no logging. For more information on logging and the Roll Forward 
utility, see “Using Btrieve Utilities” on page 83. 
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Create Btrieve Files in Pre v6.x Format 
Range: Yes or No 
Default: No 
Approximate Memory Required: Not applicable 


This option specifies that all files be created in a Btrieve version prior to v6.x. 
Use this option only if you need backward compatibility with a previous 

version of Btrieve. For example, if you want to create files with Btrieve v6.x 
and you want to use those files with Btrieve v5.x, specify Yes for this option. 


NOTE: Btrieve v6.x can read files that previous versions of Btrieve created. In 
addition, it can write to files using the existing file format. In other words, it writes 
to v5.x files using the v5.x format and writes to v6.x files using the v6.x format. 


Create Files as Transactional 
Range: Yes or No 
Default: No 
Approximate Memory Required: Not applicable 


This option controls whether Btrieve automatically flags each file as 
transactional when you create it. The transactional flag indicates that the 
NetWare Transaction Tracking System (TTS) is protecting the file. TTS 
ensures that, when a file is being modified, either all changes are made or no 
changes are made, thus preventing data damage. 


Configure BSTART.NCF to Load BROUTER 
Range: Yes or No 
Default: No 
Approximate Memory Required: Not applicable 


This option controls whether the Message Router is loaded during the 
execution of the BSTART.NCF NetWare command file. The Message Router 
allows other NLMs (such as NetWare SQL) to communicate with remote 
servers on which Btrieve is loaded. If you want to access Btrieve data on a 
remote server, specify Yes for this option. 
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Running the Setup Utility 


Use the Setup utility to set the Btrieve configuration options interactively. The 
utility automatically checks to see if the values you enter are within the correct 
ranges. 


You can run the Setup utility either at the server console or at a workstation 
running the NetWare Remote Console utility (RCONSOLE). To run the Setup 
utility, complete the following steps. 


NOTE: To get help with the Setup utility, press F1. The help information is context 
sensitive, relevant to your location in the program. To exit the utility, press the Esc 
key. 


1. Enter the following at the prompt to start the utility: 
load bsetup 


NOTE: If your SYS:SYSTEM directory does not contain the BSTART.NCF 
command file, the Setup utility displays a window asking if you want to create it. If 
that window appears on your screen, create the BSTART.NCF file at this time. 


The Available Options menu appears. 





fivailable Options 








Set Btrieve Configuration 


Set Rebuild Configuration 








This menu provides the following options: 


+ Set Btrieve Configuration—Use this option to view or modify the 
current configuration options for Btrieve. 


+ Set Rebuild Configuration—Use this option to run the Rebuild 
utility, view or modify the current Rebuild configuration options, and 
view the Rebuild log file. (“Rebuilding Existing Btrieve Files” on 
page 57 discusses the Rebuild utility and its configuration options.) 


2. To change configuration options, select Set Btrieve Configuration. 
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3. When the Current Btrieve Configuration screen appears, use the Up- and 
Down-Arrow keys to highlight the configuration option you want to 
change, and press the Enter key. A flashing cursor appears. 





Current Btrieve Configuration 


Number of Open Files: 

Number of Handles: 

Number of Locks: 

Number of Transactions: 

Largest Compressed Record Size: 
Largest Record Size: 

Largest Page Size: 


Number of Remote Sessions: 
Cache Allocation: 


Perforn Index Balancing: 

Create Files as Transactional: 

Logging of Selected Files: 

Create Btrieve files in pre vb.x format: 
Configure BSTART.NCF to Load BRouter: 








4. Use the Backspace key to remove the old value; then, type the new value 
and press the Enter key. 


If you enter an invalid value for an option, the utility displays a message 
indicating the valid values. 


NOTE: To see the valid values for any option, move the cursor to that option, press 
the Enter key, and then press the F1 key. You can also refer to “Configuration 
Options” on page 46 for more information about these options and their values. 


5. Repeat Steps 3 and 4 until you have changed all the options you want to 
modify. 


6. When you are ready to exit the Current Btrieve Configuration screen, 
press the Esc key. 
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7. When the Save Configuration Changes? screen appears, select Yes to 
save your changes or No to abandon the changes. 


If you select Yes, the Setup utility writes the configuration values you 
specified to the BSTART.NCF file. 





Save Configuration Changes? 


No 








IMPORTANT: Do not edit the BSTART.NCF command file for Btrieve. Always use 
the Setup utility to make any modifications to the configuration values in the 
BSTART.NCF file. 


Before your configuration changes can take effect, you must unload the existing 
Btrieve NLM, BSPXCOM, and the Message Router (using the BSTOP command), 
and then reload them by entering the BSTART command. 


BSTOP.NCF does not unload BSPXSTUB or RSPXSTUB. To unload these 
modules, type unload followed by the module name. 


8. To exit the Setup utility, press the Esc key until the Exit window appears, 
and then select Yes. 
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Starting and Stopping Btrieve 


This section discusses starting and stopping Btrieve. Before starting Btrieve 
v6.x, you must first check for any extraneous pre-image files (files with a 
.PRE extension) and then unload the earlier version of Btrieve. 


NOTE: If you need to preserve your Btrieve v5.x files, you can use Btrieve v6.x to 
read them. 


Checking for Extraneous Pre-Image Files 


If you have any extraneous .PRE files in your database, you must remove them 
before starting Btrieve v6.x. The following procedure explains how to check 
for and remove extraneous .PRE files. 


IMPORTANT: You must have Btrieve v5.x or v6.0 loaded before performing these 
steps. 


I; 


a A W N 


Using your existing version of Btrieve (such as v5.x or v6.0), open the 
Btrieve data file corresponding to the .PRE file in Exclusive mode. 


. Perform a Get First operation. 

. Perform an Update operation (this will not change the record). 

. Close the Btrieve data file (this should delete the .PRE file). 

. Any .PRE files that remain for the designated file after you perform Steps 


1 through 4 are extraneous. Delete them now. 


. Repeat Steps 1 through 5 to find and delete any other extraneous .PRE 


files. 


IMPORTANT: If you do not remove the extraneous .PRE files before starting 
Btrieve v6.x, file corruption may occur. 
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Unloading the Earlier Version of Btrieve 


To unload an earlier version of Btrieve from a server's memory, enter the 
following command at the server console or at a workstation running 
RCONSOLE: 


bstop 


The BSTOP command runs a NetWare command file (BSTOP.NCF) that 
unloads the following modules in the order shown: 


1. BROUTER.NLM 
2. BSPXCOM.NLM 
3. BTRIEVE.NLM 


NOTE: BSTOP.NCF does not unload BSPXSTUB or RSPXSTUB. To unload 
either of these modules, enter the UNLOAD command and the name of the 
module: 


unload bspxstub|rspxstub 


Starting Btrieve v6.x 


After installing Btrieve v6.x (as discussed in “Using the NetWare INSTALL 
Utility” on page 44), you can start it by entering the following at the server 
console or at a workstation running RCONSOLE: 


bstart 


Stopping Btrieve v6.x 


To stop Btrieve v6.x, enter the following command at the server console or at 
a workstation running RCONSOLE: 


bstop 


The BSTOP command runs a NetWare command file (BSTOP.NCF) that 
unloads the following modules in the order shown: 


1. BROUTER.NLM 
2. BSPXCOM.NLM 
3. BTRIEVE.NLM 


NOTE: BSTOP.NCF does not unload BSPXSTUB or RSPXSTUB. To unload these 
modules, type unload followed by the module name. 
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Rebuilding Existing Btrieve Files 


If your database contains files created with versions of Btrieve prior to v6.x, 
you may want to upgrade these files to take advantage of the Btrieve v6.x 
features. Btrieve v6.x works with v5.x files; however, it does not implement 
the v6.x features. 


The Btrieve Rebuild utility (BREBUILD.NLM) converts Btrieve data files to 
the v6.x format. You can run this utility from either the server console or a 
workstation running RCONSOLE. 


Use either of the following methods to run the Rebuild utility: 


¢ Interactively through the Setup utility—When you run the Rebuild utility 
interactively, it checks the values you enter to ensure they are within the 
proper ranges. 


+ From the command line—When you use this method, the utility checks 
your entries and displays messages if the values you entered are not 
within the proper ranges. With this method, you can specify a command 
file. 


The following sections discuss running the utility interactively and from the 
command line. 


IMPORTANT: Before running this utility, make sure you have unloaded your 
previous version of Btrieve, started Btrieve v6.x, and backed up all your data files. 
Having a backup copy ensures against data loss if a power interruption occurs 
while you are running this utility. 


To ensure that your backup is successful, perform one of the following: 
+ Close all Btrieve files before running the backup utility. 
+ Use continuous operations. 


+ Use a backup utility that opens the Btrieve files in exclusive write mode 
so that other processes cannot write to the files. Ensure that the backup 
utility has exclusive rights to the files. 
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Running the Rebuild Utility Interactively 


You can run the Rebuild utility interactively through the Set Rebuild 
Configuration option on the Setup utility's Available Options menu. As the 
following sections explain, you can use the Set Rebuild Configuration option 
to do the following: 


+ Configure the Rebuild utility 
+ Execute the Rebuild utility 


+ Check the utility's error log 


Configuring the Rebuild Utility 


Complete the following steps to set the configuration options that apply to 
rebuilding your Btrieve files: 


1. After starting Btrieve v6.x, load the Setup utility by entering the 
following at the prompt. 


load bsetup 


2. When the Available Options menu appears, select Set Rebuild 
Configuration to run the Rebuild utility. 





fivailable Options 








Set Btrieve Configuration 


set Rebuild Configuration 








A warning appears, indicating you should back up your Btrieve data files 
before proceeding. 





WARNING: Before rumning the Rebuild Utility, be 
sure to back up all your Btrieve data filez. 
<Press ESCAPE To Continue> 





NOTE: If you do not have current backups, you should press Esc three times. 
When the Exit Btrieve Setup? prompt appears, select Yes. Create backups and 
then return to this utility. 
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3. Provided you have current backups of your data files, press Esc to 
continue to the Rebuild Options menu. 


Rebuild Options 





Set Rebuild Configuration 


Execute Rebuild 
View Rebuild Log File 








4. Select Set Rebuild Configuration to display the Rebuild Configuration 
Setup Form screen. 


Rebuild Conf iguration Setup Form 


Files To Be Converted: 





Dutput Directory: 
AUS-PUBS/5 15 : 


Page Size: AUTO Conversion Method: PRIMARY 


Key Number: -1 Continue On Error: No 


Preserve TTS setting: No Convert Supplemental Indexes: No 








5. Select the files you want to rebuild, as follows: 


a. With your cursor at Files To Be Converted, press Enter and then 
Insert. 


b. When the list of available volumes appears, highlight the volume you 
want and press Enter. 


The utility displays the directories available on the selected volume. 
c. Highlight the directory you want and press Enter. 


d. Continue highlighting directories (that is, subdirectories) and 
pressing Enter until you have reached the one that contains the file or 
files you want to rebuild. Then, press Esc. 
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e. Choose the files you want to rebuild, as follows: 


To specify more than one file, enter the filenames manually, using 
wildcard characters (* or ?). For example, you might enter /*.* to 
specify all files in the selected directory, or you could enter /*.BTR 
to specify all files in that directory with the extension .BTR. 


To specify an individual file, press Enter to list the filenames in the 
specified directory. Highlight the filename you want, and press Enter 
to select it. (The input files that are listed are on the local server.) 


6. At Output Directory, specify the location you want to use for the rebuilt 
files, as follows. (The default location is the directory you specified for 
the Files To Be Converted field.) 


a. Press Enter. 


b. Either type the server or directory name manually and press Enter, or 
choose from the list of available directories on the current server by 
entering a valid path and pressing Insert. To select a directory name 
from the list, highlight the name and press Enter. 


If you want to place the rebuilt files on a different server, you must 
type the output server name, volume, and path manually. Then, press 
Enter. 


NOTE: To place rebuilt files on a different server, Btrieve and the Message 
Router must be loaded on the server where the original data files reside, and 
the Btrieve and BSPXCOM NLMs must be loaded on the server that will 
contain the rebuilt files. Wherever you locate the rebuilt files, you will need 
enough disk space for the rebuilt files and the temporary files that the utility 
creates. The utility deletes the temporary files at the end of the conversion 
process. 


Do not use wildcard characters in the pathname that specifies the 
location for the rebuilt files. 


c. After specifying the output directory, use the Down-Arrow key to 
move to the Page Size field. 


7. At Page Size, type the size manually or choose from a list of sizes. 


To list the available page sizes, press Enter. In this list, the AUTO option 
(the default) means the utility will choose the optimum page size for the 
files. The EXISTING option means the utility will use the same page size 
as that of the original files. To select a size from the list, highlight it and 
press Enter. 
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NOTE: When you use the EXISTING option, the utility changes the page size if 
the original size will not work. For example, assume you have a Btrieve v5.x file 
with a page size of 1,024 and 24 keys. Since Btrieve v6.x supports only 23 keys 
for a file of that page size, the utility selects a new page size for the file and displays 
an informative message on the screen. 


8. At Key Number, specify a number between 0 and 23 on which to sort the 
records, or specify -1 to sort the records in physical order; then, press 
Enter. 


IMPORTANT: If you are using NetWare SQL, you must specify a key number of 
0 when rebuilding the VIEW.DDF file. 


9. At Preserve TTS Setting, specify Y (for Yes) or N (for No) to indicate 
whether you want to preserve the Transaction Tracking System (TTS) bit 
during conversion; then, press Enter. 


If you specify Y, the utility preserves the bit. If you specify N (the 
default), the utility clears the bit when creating Btrieve v6.x files. 


10. At Conversion Method, select the conversion method as follows: 
a. Press Enter. 


b. Highlight either PRIMARY (the default) or SECONDARY, and then 
press Enter. 


The PRIMARY method clones the files, drops the indexes, copies the 
records into the new files, and rebuilds the indexes. Since this 
method is faster and creates smaller files, you should use this method 
whenever possible. However, if you are using NetWare SQL, you 
must not use this method when rebuilding the VIEW.DDF file. 


The SECONDARY method clones and copies the files without 
dropping and replacing indexes. This method may be slower than the 
Primary method. 


IMPORTANT: If you are using NetWare SQL, you must specify the 
SECONDARY method when rebuilding the VIEW.DDF file. The 
SECONDARY method may create a v6.x file in which the records are in a 
different physical order than in the original v5.x file. 


11. At Continue On Error, specify either Y (for Yes) or N (for No) and press 
Enter. 


If you specify Y, the utility continues if it encounters an error. (The utility 
notifies you of non-Btrieve files or other errors but continues rebuilding 
Btrieve files.) If you specify N, the utility stops if it encounters an error 
and aborts the rebuild process. 
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12. At Convert Supplemental Indexes, specify Y (for Yes) or N (for No) and 
press Enter. 


If you specify Y, the utility converts Btrieve v5.x supplemental indexes 
(which allow duplicates) to Btrieve v6.x indexes with linked duplicates. 
Btrieve v5.x supplemental indexes have, by default, repeating duplicates. 


If you specify N (the default), the utility does not convert the v5.x 
supplemental indexes but preserves them as repeating duplicates. 


IMPORTANT: Do not use the Convert Supplemental Indexes option if you access 
your data files through NetWare SQL. 


13. Press Esc to leave the Rebuild Configuration Setup Form screen. 


14. When the utility asks whether to save your changes, select Yes to save 
them and return to the Rebuild Options menu or No to abandon the 
changes. 


IMPORTANT: The utility applies the Btrieve v5.x file's owner name and level to 
the Btrieve v6.x file. 


Executing the Rebuild Utility 


After configuring the Rebuild utility, you are ready to rebuild your files. At the 
Rebuild Options menu, select Execute Rebuild to run the utility. 


Rebuild Options 





set Rebuild Conf iquration 


Execute Rebuild 
Vieu Rebuild Log File 








The utility executes and also creates a log file. It then notifies you that the 
process has completed. To return to the Rebuild Options menu, press Esc. You 
can then check the log file as discussed in the following section. 
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Checking the Rebuild Log File 


After rebuilding your files, be sure to check the utility's log file to see if any 
errors occurred during the conversion, as follows: 


1. Select View Rebuild Log File from the Rebuild Options menu. 


Rebuild Options 


Set Rebuild Configuration 
Execute Rebuild 


iew Rebuild Log File 











The utility displays a log of any errors that occurred while the utility was 
executing, similar to the following example: 


BREBUILD-1.1-33: The BREBUILD start time is 11-20-92 12:19:22a. 

BREBUILD -M2 -P -t —BAUS-PUBSSYS : «USERS «HOMEARA-QUTPUT SY5: -USERS“MONEARA, INF 
BREBUILD-1.1-20: BREBUILD is processing 5Y5:/USERS/MOMEARA- INPUT/BATT ING. DAT. 
BREBUILD-1.1-36: The page size will be changed to 4096. 

EREBUILD-1.1-32: BREBUILD copied a total of 166 records. 

The file was rebuilt successfully. 

BREBUILD-1.1-33: The BREBUILD start time is 11-20-92 12:20:40a. 

BREBUILD -M2 -P -t —BAUS-PUBS/545 : “USERS/MOMNEARA/OUTPUT SY5: «USERS -HOMEÁARA, INF 
BREBUILD-1.1-20: BREBUILD is processing SY5:/USER5/MOMEARA, INPUT/BTEANS . DAT. 
BREBUILD-1.1-36: The page size will be changed to 4096. 

BREBUILD-1.1-32: BREBUILD copied a total of 166 records. 

The file was rebuilt successfully. 

BREBUILD-1.1-33: The BREBUILD start time is 11-20-92 12:21:16a. 

BREBUILD -Mż -P -t —BAUS-PUBS/S¥5 : “USERS/MOMEARA/OUTPUT SY5: USERS-MOMEÁARA, INP 
BREBUILD-1.1-20: BREBUILD is processing SY39: /USERS-MNOMEARA INPUT/J. DAT. 
BREBUILD-1.1-36: The page size will be changed to 4096. 

BREBUILD-1.1-32: BREBUILD copied a total of 166 records. 

The file was rebuilt successfully. 








2. When you finish viewing the log, press Esc to return to the Rebuild 
Options menu. To exit both the Rebuild utility and the Setup utility, press 
Esc twice more and specify Yes at the Exit Btrieve Setup? prompt. 
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Running the Rebuild Utility from the Command Line 


Before running the Rebuild utility from the command line, make sure you 
have unloaded your previous version of Btrieve, started Btrieve v6.x, and 
backed up all your data files. Having a backup copy ensures against data loss 
if a power interruption occurs while you are running this utility. 


NOTE: After rebuilding your files, be sure to check the utility's log file to see if any 
errors occurred during the conversion. The log file (BREBUILD.LOG) that the 
Rebuild utility creates is an ASCII text file. The .LOG file is placed in the 
SYS:SYSTEM directory. You can view it by using a text editor or by running the 
Rebuild utility interactively and selecting View Rebuild Log File from the Rebuild 
Options menu (as explained in “Checking the Rebuild Log File” on page 63). 


To run the Rebuild utility from the command line, enter the following command at 
the prompt: 


LOAD BREBUILD [-option ...] file 
or 


LOAD BREBUILD @commandFile 





option Specifies the configuration options for the utility. Precede each option letter with a 
dash (-). Do not place a space between the dash and the option letter and between 
the option letter and its value. You can enter the option letter in uppercase or 
lowercase. 


-B[path] Specifies an alternate location for the rebuilt files. (The 
default location is the current directory.) This option lets you 
rebuild large files on a different volume or on a different 
server. 


To locate the files on a different server, the Btrieve NLM and 
the Message Router must be loaded on the server where the 
original data files reside, and the Btrieve and BSPXCOM 
NLMs must be loaded on the server that will contain the 
rebuilt files. 





IMPORTANT: Do not use wildcard characters in the pathname you specify with 
the -B option. 





-C Instructs the utility to continue with the next file even if an 
error occurs. The utility notifies you of non-Btrieve files or 
other errors but continues updating Btrieve files. This option 
is useful if you have specified wildcard characters for the 
rebuilt files. 
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-D Converts Btrieve v5.x supplemental indexes (which allow 
duplicates) to v6.x indexes with linked duplicates. (By 
default, the utility preserves the indexes as repeating 
duplicates.) If you access your data files only through Btrieve 
and your files have a relatively large number of duplicate 
keys, you can use this option to enhance the performance of 
the Get Next and Get Previous operations. 





IMPORTANT: Do not use the -D option if you access your data files through 
NetWare SQL. 





-MO | M2 Specifies the conversion method, as follows: 


MO Clones and copies the files without 
dropping and replacing indexes. 
While this method is slower than M2, 
it is available in case you do not want 
to rebuild your indexes. 





IMPORTANT: If you are using NetWare SQL, you must use the -MO and -KO 
options to rebuild the VIEW.DDF file. 





M2 (Default) Clones the files, drops the 
indexes, copies the records into the 
new files, and rebuilds the indexes. 
Since this method is faster and 
creates smaller files, you should use it 
whenever possible. 





IMPORTANT: The M2 method may create a v6.x file in which the records are in a 
different physical order than in the original v5.x file. 





-P[nnn] Specifies the page size (in bytes) of the new files. If you 
specify -P with no page size, the utility chooses the optimum 
page size for your file. 





IMPORTANT: If you do not specify the -P parameter, the utility will change the 
page size if the original size will not work. 
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-K[nn] 





For example, assume you have a Btrieve 5.x file with a page 
size of 1,024 and 24 keys. Since Btrieve v6.x supports only 
23 keys for a page size of 1,024, the utility automatically 
selects a new page size for the file and displays an 
informative message on the screen. 


Specifies the key by which the utility reads when rebuilding 
a file. If you do not specify this option, the utility reads the file 
in physical order. 


IMPORTANT: You must use the -KO option when rebuilding NetWare SQL's 


VIEW.DDF file. 





Does not preserve the Transaction Tracking System (TTS) 
bit during conversion. If you specify this option, the utility 
clears the TTS bit (if set) when converting a Btrieve v5.x file 
to a Btrieve v6.x file. If you do not specify this option, the 
utility sets the TTS bit when creating the Btrieve v6.x file if 
the v5.x file had the TTS bit set. 


file Specifies the set of files to convert. Use full directory names, including the volume 
name. You may use wild cards (* and ?) in these filenames. 





IMPORTANT: The Rebuild utility applies the Btrieve v5.x file's owner name and 
level to the Btrieve v6.x file. 





@commandFile 


Specifies a command file for the utility to execute. You can include multiple entries 
in one command file. Each entry in the command file contains the utility options (if 
any) and the set of files to convert, followed by <end> or [end]. When specifying the 
files to convert, be sure to use full directory names, including the volume name. You 
may use wildcards (* and ?) in these filenames. The following is an example of a 
Rebuild utility command file: 


-C sys:\mydir\*.* <end> 


-C -P1024 dta:\dir\*.* <end> 


-MO -KO sys:\nwsql\*.* <end> 
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Examples 


The first example places the rebuilt files on another server: 


load brebuild -Bserv-temp\sys:\newfiles -C -P4096 
sys:\oldfiles\*.btr 


The next example places the rebuilt files on the same server, but on a different 
volume: 


load brebuild -Bvol2:\btrfiles -C -P4096 -M2 
sys:\btrfiles\*.btr 


Deleting Temporary Files 


By default, the Rebuild utility creates temporary files in the same directory in 
which the conversion takes place. (You can specify a different directory by 
using the -B option when running the Rebuild utility from the command line, 
or by using the Output Directory option on the Setup Form screen when 
running the utility interactively.) 


You need enough disk space to accommodate the original file and the new file 
while the Rebuild utility is running. 


NOTE: The Rebuild utility deletes the original file after rebuilding it, even if the new 
file is in a different directory. 


Normally, the Rebuild utility automatically deletes temporary files when the 
conversion is complete. However, if a power failure or other serious interruption 
occurs, the Rebuild utility may not delete the temporary files. If this occurs, look for 
filenames such as _T-xxxxx.TMP and delete them. 


Using Btrieve with NetWare Runtime 


The NetWare Runtime serialized NetWare operating system differs from the 
other versions of NetWare in that 1t grants file service access to only one 
NetWare login client connection. This login is for system administration 
purposes. 


NetWare Runtime does not limit the number of SPX or AppleTalk connections 
between client applications and NLM-based services. Consequently, NetWare 
Runtime does not limit the number of users that can access Btrieve running on 
the Runtime server. 
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Figure 8 illustrates the relationship between NetWare Runtime and a NetWare 
configuration that is not dedicated to database services. 


Figure 8 NetWare Configurations 
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Reasons to Use NetWare Runtime 


Running NetWare Btrieve on a server dedicated to database management 
ensures that all the server's processing power is directed toward database 
applications. If you anticipate heavy file service activity, a dedicated database 
server makes that activity more efficient because it frees the nondedicated 
server to devote all its resources to file services. 


Having a dedicated database server is also particularly effective in preventing 
slow performance on the network during periods of heavy file service activity. 
To optimize network performance, you can configure so as to include a 
dedicated database server in addition to other servers offering full NetWare 
services. 


68 Btrieve Installation and Operation 


Figure 9 shows an example installation for NetWare Runtime. 


Figure 9 NetWare Runtime Installation 
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Installing NetWare Runtime 


The installation procedure for NetWare Runtime is identical to installing the 
other versions of NetWare. Refer to the documentation that accompanies your 


NetWare Runtime software for instructions. 


Special Notes on NetWare Runtime 


NetWare Runtime supplies a facility (NLICLEAR.NLM) that clears unused 

connections. NetWare Runtime provides only one available client connection. 
Even after the administrator logs out of the application server, a connection is 
maintained between the workstation and the server. If a second administrator 
wants to log on to the application server from a second workstation, the single 


connection will be unavailable. 


The NLICLEAR facility is important for NetWare Runtime because, at 


intervals, NLICLEAR automatically clears the unused connections left after 


an administrator logs out of the application server, allowing another 


administrator to log in to and administer the database server. 
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Special Notes on Btrieve 


When you load the Btrieve DOS or OS/2 Requester using the option /C:1, 
username, password, Btrieve logs in to the NetWare Runtime server with the 
specified username and the corresponding password. Btrieve also obtains a 
temporary connection number, which it uses to distinguish between users. 


Btrieve verifies that the user has the acceptable rights to open or create a file. 
Btrieve then logs out of the server, using the temporary connection number. If 
the user has the appropriate file access rights, Btrieve continues; otherwise, it 
returns an error. 


NOTE: The administrator must set up file access rights on the NetWare Runtime 
server. 


When you load the Btrieve DOS or OS/2 Requester using the /C:1 default 
option (without specifying a username and password) and then attempt to read 
a file on the NetWare Runtime server, the Requester must determine what 
login username Btrieve can use to maintain NetWare security. Btrieve then 
uses that username to log in temporarily for the client. 


In contrast, if the Requester detects that there is no connection, or if it cannot 
find a valid login username, the Requester returns an error. 


For more information about the NetWare Runtime server support option 
available with the DOS and OS/2 Requesters, see “Configuring and Using the 
Requesters” on page 71. 


70 Btrieve Installation and Operation 





Configuring and Using the Requesters 


Btrieve provides a DOS Requester, an OS/2 Requester, a Windows Requester, 
and a Unix Ware Requester. This chapter provides configuration options and 
instructions for loading and unloading the Requester in each operating 
environment. 


NOTE: The Btrieve Requesters have changed (primarily in key definition) between 
previous versions and Btrieve v6.1. Therefore, all workstations accessing the 
Btrieve v6.1 NLM must use the Btrieve v6.1 Requesters. 


For information about the new UnixWare Requester, please refer to the Readme 
file that accompanies this release. 


DOS Requester 


You must load the Btrieve DOS Requester, BREQUEST.EXE, at a 
workstation running DOS before that workstation can access network Btrieve 
files using the Btrieve NLM. 


The DOS Requester loads into a DOS workstation's memory as a Terminate 
and Stay Resident (TSR) program. You can access local as well as remote files 
by running both client-based (local) Btrieve and the Requester at your 
workstation. 


NOTE: Client-based Btrieve is available only as part of the Btrieve Developer's Kit 
and must be purchased separately. 
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DOS Requester Configuration Options 


There are five configuration options for the Btrieve DOS Requester: NetWare 
Runtime Server Support (/C), Data Message Length (/D), DOS Session Load 
(/L), Real-Time Data Compression (/O), and Help (/?). Previous versions of 
the DOS Requester also supported the /S and /R options. The DOS Requester 
v6.x accepts the /S and /R options for backwards compatibility, but otherwise 
ignores them. 


NetWare Runtime Server Support (/C) 


Range: None 
Default: /C:1 
Memory Required: Not applicable 


This option allows you to enable or disable NetWare Runtime server support. 


/C:0 | /c:1 | /C:1,username, password 





/C:0 


1C:1 


/ 
C:1,usernamep 
assword 


Disables NetWare Runtime server support. 


Enables NetWare Runtime server support. Btrieve looks at the username for the drive 
(current server) on which you are presently running. 


If the username is SUPERVISOR, Btrieve searches for another username in the table 
of usernames for the servers onto which you are logged. 


If the username is not SUPERVISOR, Btrieve searches for that username on the 
NetWare Runtime server. If it is not a valid username, Btrieve returns an error at the time 
of the Open or Create request. 


Enables NetWare Runtime server support. Btrieve verifies the specified username and 
password for the NetWare Runtime server. Btrieve returns an error if the specified 
username is not found or the password is invalid. 


username Preferred login name on the NetWare Runtime server. 


NOTE: If you specify SUPERVISOR for the username, Btrieve returns an error and 
the DOS Requester will not load. 
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password Login password for the specified user. 





For information on using Btrieve with NetWare Runtime, see “Installing and 
Configuring Btrieve” on page 43. 


Data Message Length (/D) 
Range: 532 through 57,000 bytes 
Default: 4,096 bytes 
Memory Required: 538 bytes + data message length 


This option specifies the length of the largest record (or the largest portion or 
chunk of a record) you want to access through Btrieve. (If you omit this 
option, the Requester uses the default value, 8,192.) The Requester uses this 
value to calculate the length of the data message buffer reserved for passing 
records between Btrieve and your applications. The Requester maintains one 
copy of the data message buffer. 


The value you enter here should not exceed the largest record size you 
configure for Btrieve through the Setup utility since that is the maximum 
message that BSPXCOM can receive. (For more information, refer to the 
section “Largest Record Size” on page 48.) 


Specify the data message length in bytes. For example, if the largest record 
your application uses is 3,000 bytes, specify the /D option as follows: 


/4:3000 


NOTE: Specifying a higher value than you need for the /D option does not improve 
performance and may waste memory. 


DOS Session Load (/L) 
Range: Not applicable 
Default: Not applicable 
Memory Required: Not applicable 


This option allows you to load another instance of BREQUEST even if it is 
already loaded. This option is useful if you want to run Windows applications 
using the DOS Requester while running DOS VM applications that are also 
using the DOS Requester. 


Configuring and Using the Requesters 73 


To run Windows applications that use the DOS Requester, you must load 
BREQUEST before starting Windows. In order to run DOS applications in 
Windows, you must load BREQUEST in each DOS session. However, if you 
load BREQUEST outside Windows, you cannot load it again in a DOS 
session. 


For Windows applications using the DOS Requester, load BREQUEST 
outside Windows. In each Windows DOS session that will be running a 
Btrieve application, load BREQUEST with the /L option. Doing so loads 
another instance of BREQUEST that is available only to the DOS session. 


This operation provides the DOS session with its own copy of BREQUEST 
and prevents the DOS session from using the instance of BREQUEST that you 
loaded before starting Windows. 


Real-Time Data Compression (/O) 
Range: None 
Default: No compression 


Memory Required: Approximately 32 KB on the workstation and 32 KB per 
client on the server 


In many cases (such as when implementing extended reads and VATs), this 
option can help reduce network traffic by reducing the number of packets 
required to complete a request to Btrieve. This option may, however, 
adversely affect memory and performance. 


Compressing and decompressing data takes extra CPU time on both the server 
and client sides. Because of overhead, you should not use this option with fast 
networks or with slow workstations for clients. 


Help (/?) 


The /? option lists the other options that are available (/C, /D, and /O) and 
mentions that although the /S and /R options are accepted for backwards 
compatibility, Btrieve v6.x ignores them. 
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Loading the DOS Requester 


path 


option 


Load the DOS Requester at the workstation by entering the following 
command: 


[path] brequest [option] 


The pathname to the directory where the DOS Requester is stored. You can omit the 
pathname if the DOS Requester is stored on the default drive, or if it is located in a 
directory in your search path. 


Any of the configuration options (/C, /D, /L, /O, or /?). 





For example, if the Requester is on the default drive and you want to specify 
a 2,048-byte data message length, enter the following: 


brequest /d:2048 


NOTE: The forward slash (/) before the configuration option is the only valid 
character you can use. If you specify a dash (-) or a backslash (\), the Requester 
may load improperly. 


Unloading the DOS Requester 


To unload the DOS Requester, use the DOS Requester utility, 
BREQUTIL.EXE. At the workstation where the DOS Requester is loaded, 
enter the following: 


brequtil -stop 
To determine the version number of your DOS Requester, enter 
brequtil -ver 


NOTE: If files remain open (as happens, for example, when an application does 

not issue a Close operation for each open file), simply logging out of one or more 
servers from a workstation does not close Btrieve files or terminate the Btrieve SPX 
connection to the server. To close Btrieve files and terminate the connection, use 
the BREQUTIL -STOP command. 
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OS/2 Requester 


The following files must be loaded in a directory listed in an OST2 
workstation's LIBPATH before a Btrieve application can access the Btrieve 
NLM from that workstation: 


+ BTRCALLS.DLL—The Btrieve dynamic link Requester for OS/2 
workstations. 


+ NDBCOMM.DLL—The communications Requester for OS/2 
workstations. NDBCOMM.DLL provides the necessary data 
communications between the workstation and the Btrieve NLM. 


You can access local as well as remote files by running both client-based 
(local) Btrieve and the Requester at your workstation. 


If you want to run both client-based Btrieve and the Requester, you must use 
the OS/2 Conversion utility (NDBCNVT.EXE) to convert the client-based 
BTRCALLS.DLL to BTRLOCL.DLL. (By default, the Requester and client- 
based Btrieve have the same name.) 


NOTE: Client-based Btrieve is available only as part of the Btrieve Developer's Kit 
and must be purchased separately. 


OS/2 Requester Configuration Options 


You are not required to specify any configuration options for the OS/2 
Requester. Since the internal tables that control the options are not fixed, the 
tables will grow as needed. 


There are three configuration options for the OS/2 Requester: NetWare 
Runtime Server Support (/C), Data Message Length (/D), and Number of 
Servers (/S). 


NOTE: Although you can set the initial size of the tables using the Data Message 
Length (/D) and the Number of Servers (/S) options, setting table sizes is not 
recommended. 
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NetWare Runtime Server Support (/C) 
Range: None 
Default: /C:1 
Memory Required: Not applicable 


This option allows you to enable or disable NetWare Runtime server support. 


/C:0 | /C:1 | /C:1, username, password 





/C:0 Disables NetWare Runtime server support. 


/C:1 Enables NetWare Runtime server support. Btrieve looks at the username for the drive 
(current server) on which you are presently running. 


If the username is SUPERVISOR, Btrieve searches for another username in the table 
of usernames for the servers onto which you are logged. 


If the username is not SUPERVISOR, Btrieve searches for that username on the 
NetWare Runtime server. If it is not a valid username, Btrieve returns an error at the time 
of the Open or Create request. 


/ Enables NetWare Runtime server support. Btrieve verifies the specified username and 
C:1,usernamep password for the NetWare Runtime server. Btrieve returns an error if the specified 
assword username is not found or the password is invalid. 

username Preferred login name on the NetWare Runtime server. 





NOTE: If you specify SUPERVISOR for the username, Btrieve returns an error and 
the OS/2 Requester will not load. 





password Login password for the specified user. 





For information on using Btrieve with NetWare Runtime, see “Installing and 
Configuring Btrieve” on page 43. 
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Data Message Length (/D) 
Range: 532 through 65,000 bytes 
Default: 4,096 bytes 
Memory Required: 538 bytes + data message length 


The /D option specifies the length of the largest record (or the largest portion 
or chunk of a record) you want to access through Btrieve. The OS/2 Requester 
uses this value to calculate the length of the data message buffer reserved for 
passing records between Btrieve and your applications. The Requester 
maintains one copy of the data message buffer. 


The value you enter here should not exceed the value you specified for the 
Largest Record Size configuration option in the Setup utility. (For more 
information, refer to the section “Largest Record Size” on page 48.) The value 
for this option represents the maximum message length that BSPXCOM can 
receive. 


Specify the record length in bytes. For example, if the largest record your 
application uses is 3,000 bytes, specify the /D option as follows: 


/4:3000 


NOTE: Specifying a higher value than you need for the /D option does not improve 
performance. 


Number of Servers (/S) 
Range: 1 through 255 
Default: 8 
Memory Required: 27 bytes per server 


The /S option specifies the number of servers that have the Btrieve NLM 
active on the network. 
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Configuring the OS/2 Requester 


Set the Requester configuration options using the following command: 


set brqparms=option 


option Any of the three configuration options (/C, /D, or /S). 





Do not include a space between BRQPARMS and the equal sign. You can, 
however, insert a space between each configuration option you specify. 


For example, to specify a 10,240-byte data message length and four servers, 
issue the following command: 


set brqparms=/d:10240 /s:4 


NOTE: The forward slash (/) before the configuration option is the only valid 
character you can use. If you specify a dash (-) or a backslash (\), the Requester 
may load improperly. 


Loading the OS/2 Requester 


An application may load the Btrieve for OS/2 Requester in one of the 
following two ways: 


¢ Implicitly—Your application can implicitly load the OS/2 Requester 
either by linking with the import library BTRCALLS.LIB or by 
specifying imported functions in the application definition file. In either 
case, the operating system loads the OS/2 Requester automatically when 
the application is started. 


+ Explicitly—yYour application can load the OS/2 Requester explicitly 
using the operating system API functions. When the application loads the 
Requester explicitly, the operating system does not load the OS/2 
Requester until notified to do so. 


Unloading the OS/2 Requester 


At an OS/2 workstation, the operating system removes the dynamic link 
routines from memory when the application terminates or when the 
application explicitly unloads the OS/2 Requester using the operating system 
API. 


NOTE: If files remain open (as happens, for example, when an application does 
not issue a Close operation for each open file), simply logging out of one or more 
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servers from a workstation does not close Btrieve files or terminate the Btrieve SPX 
connection to the server. To close files and terminate the connection, you must 
either unload the Requester or restart the workstation. 


Windows Requester 


In the Windows environment, you must load the DOS Requester, 
BREQUEST.EXE, before starting Windows. Windows-based Btrieve 
applications access the Requester by means of a DLL, WBTRCALL.DLL, 
which uses the DOS Protected Mode Interface (DPMI) that Windows 
provides. 


The Windows Requester (that is, WBTRCALL.DLL) is the Btrieve interface 
DLL for Windows v3.x. The DLL provides the same API as client-based 
Btrieve and requires no modification to the application. 


You can access local as well as remote files by running both client-based 
(local) Btrieve and the Requester at your workstation. If you want to run both 
client-based Btrieve and the Requester, you must run the Windows 
Conversion utility (WNDBCNVT.EXE) to convert the client-based 
WBTRCALL.DLL to WBTRLOCL.DLL. 


NOTE: Client-based Btrieve is available only as part of the Btrieve Developer's Kit 
and must be purchased separately. 


Windows Requester Configuration Options 


Tasks=# 


Local=Yes/No 


Chkparms=Yes/No 


The following list describes the available configuration options for the 
Windows Requester. These options should be specified in the NOVDB.INI 
file under [brequestDPMI]. 


NOTE: NOVDB.INI is the Novell initialization file for the Windows Requester. It is 
included on the distribution diskette 


Specifies how many concurrent tasks may use the Windows 
Requester. The range is 1 through 255. The default value is 10. 


Instructs the Windows Requester to use client-based Btrieve 
for accessing files locally. The default value is No. 


Instructs the Windows Requester to validate pointers passed to 
it. You should use this option only during development. The 
default value is No. 
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Free Memory=Yes/No Allocates and frees real-mode memory on each request. The 
Windows Requester uses a buffer of real-mode memory to 
communicate with the DOS Requester. Since real-mode 
memory is a scarce resource in Windows, your application 
should not retain it long term. The default value is No. 


NOTE: Specifying Yes to the Free Memory option degrades 
performance. 





Loading the Windows Requester 


The DOS Requester must be loaded before the Windows Requester can load. 
If you want to run Windows Btrieve applications, the DOS Requester must be 
loaded in the DOS environment before you start Windows. To load the DOS 
Requester, use the WINSTART.BAT file or type the following at the DOS 
prompt before loading Windows: 


brequest 


An application may load the Windows Requester in one of the following two 
ways: 


¢ Implicitly—Your application can implicitly load the Windows Requester 
by either linking with the import library WBTRCALL.LIB or by 
specifying imported functions in the application definition file. When an 
application loads a DLL implicitly, the operating system automatically 
loads the DLL when the application is started. 


+ Explicitly—Your application may load the Windows Requester explicitly 
using the operating system API functions. The operating system does not 
load the DLL until notified to do so. 


NOTE: If you want to run a DOS Btrieve application in the DOS box and a 
Windows Btrieve application at the same time, you must have the DOS Requester 
loaded in each DOS session. However, if you have already loaded the DOS 
Requester before loading Windows, you cannot load the DOS Requester in any 
subsequent DOS session. Consequently, you cannot run the DOS Btrieve 
application in the DOS box. 


For Windows applications using the DOS Requester, load BREQUEST outside 
Windows. In each Windows DOS session that will be running a Btrieve application, 
load BREQUEST with the /L option. Doing so loads another instance of 
BREQUEST that is available only to the DOS session. This operation provides the 
DOS session with its own copy of BREQUEST and prevents the DOS session from 
using the instance of BREQUEST that you loaded before starting Windows. 
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Unloading the Windows Requester 


At a Windows workstation, the operating system removes the dynamic link 
routines from memory when the application terminates or when the 
application explicitly unloads the DLLs using the operating system API 
functions. 


NOTE: If Btrieve files remain open in an application because the application did 
not issue a Close operation, simply logging out of one or more servers from a 
workstation does not close the files or terminate the Btrieve SPX connection to the 
server. The files remain open until you restart the workstation or unload the DOS 
Requester using the BREQUTIL -STOP command. Also, keep in mind that a Reset 
operation closes files but does not unload the DOS Requester. 
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Using Btrieve Utilities 


This chapter provides the following sections: 


+ “Btrieve Monitor Utility” on page 83—This utility monitors the activity 
of Btrieve. 


+ “Btrieve Maintenance Utility” on page 97—This utility imports and 
exports Btrieve data and transfers data from one Btrieve file to another. 


+ “Roll Forward Utility” on page 122—This utility recovers changes made 
to a Btrieve file between the time of the last backup and a system failure. 


Btrieve Monitor Utility 


The Btrieve Monitor utility (BTRMON.NLM) allows you to monitor Btrieve 
activities on a server. It provides information that is useful for both database 
administration and application programming diagnostics. 


NOTE: The information you receive from the Btrieve Monitor utility pertains only to 
the activity of the NLMs on the current server. 


The Btrieve Monitor utility runs as an NLM at the server. You can access it at the 
server console or through RCONSOLE at your workstation. 


Using Btrieve Utilities 83 


System Requirements 
To run the Btrieve Monitor utility, be sure that the following software is loaded 
on your server: 
+ NetWare v3.12 
+ Btrieve v6.1 or later 
+ BSPXCOM, BSPXSTUB, or RSPXSTUB 


NOTE: Running Btrieve v6.1 in a NetWare v3.12 environment requires 
AFTER311.NLM, which Btrieve loads automatically. 


In addition, the following files must be located in the SYS:SYSTEM directory 
of the server: 


+ BTRMON.NLM 
+ BTRMON.HLP 


NOTE: The NetWare INSTALL utility automatically places these files in the 
SYS:SYSTEM directory. 


Starting the Btrieve Monitor Utility 
To start the Btrieve Monitor utility, enter the following command at the server 
console prompt: 


load btrmon 


Alternatively, you can include the command line option /R with the LOAD 
command. The /R option specifies the update time for the statistics screens 
that the utility dynamically updates. The range of valid values for this option 
is from 500 to 60,000 milliseconds; the default value is 2,000 milliseconds. 


For example, if you want to start the Btrieve Monitor utility and instruct it to 
update the statistics screens every 3,500 milliseconds, enter the following 
command: 


load btrmon /r3500 
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Selecting Options from the Available Options Menu 


The Available Options menu is the first screen you see after starting the 
Btrieve Monitor utility: 


Available Options 


Active Resources 


User Information 
Resource Usage 
Communication Statistics 








You can select one of the following options from the Available Options menu: 


+ Active Resources—Displays information about active Btrieve data files. 
For more information, see “Monitoring Btrieve Files with the Active 
Resources Option” on page 86. 


+ User Information—Displays information about the users currently using 
the Btrieve NLM. This option also allows you to delete a user's SPX 
connection. For more information, see “Monitoring Btrieve Users with 
the User Information Option” on page 87. 


+ Resource Usage—Shows current, peak, and maximum usage statistics for 
the Btrieve NLM. For more information, see “Monitoring Resources with 
the Resource Usage Option” on page 92. 


+ Communication Statistics—Displays Sequenced Packet Exchange (SPX) 
protocol statistics for the communications module you have loaded 
(BSPXCOM, BSPXSTUB, or RSPXSTUB). For more information, see 
“Monitoring SPX Activity with the Communication Statistics Option” on 
page 94. 


NOTE: When you are using the Btrieve Monitor utility, the statistics on the File 
Information, User Information, Resource Usage, and Communication Statistics 
screens are updated regularly. On the Active Btrieve Files and Active Btrieve Users 
screens, you must press the Insert key to see updated statistics. 


While running the Btrieve Monitor utility, you can return to the previous 
screen at any time by pressing the Esc key. To exit the utility, press Esc at the 
Available Options menu. When the Exit window appears, select Yes to verify 
that you want to exit. 
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Monitoring Btrieve Files with the Active Resources Option 


You can use the Active Resources option on the Available Options menu to do 
the following: 


¢ List all active (open) files 
¢ Display additional information about a particular file 


¢ List all users accessing a particular file 


Listing Active Files 


To list all active Btrieve files, select Active Resources from the Available 
Options menu. The utility displays a scrollable list of active Btrieve files. 


The file pathnames appear in alphabetic order. To update the list of active 
Btrieve files, press Insert. 


Displaying Additional Information About an Active File 


For further information about a particular file, highlight the desired file listed 
in the Active Btrieve Files screen and press Enter. The utility displays a File 
Information screen similar to the following, providing information about the 
file you selected. 





SYS : NUSUL-DEMODATA-PATIENTS . DTA 


Hand les :1 
Open Mode : NORMAL MODE 
Page Size : 2046 


TTS Flag 

Read-Only Flag 
Record Locks : N 
Transaction Lock: Ħ 








Since the utility dynamically updates the statistics shown on this screen, you 
may notice the values changing as you view the screen. 


For a description of each field that appears on this screen, refer to Table 2. 
Table 2 lists, in alphabetic order, all fields associated with the Active 
Resources and User Information options. 
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Listing Users Accessing a File 


From the Active Resources option's File Information screen, you can list all 
users accessing the designated file. Press Enter to display a scrollable list of 
active Btrieve users. (See Table 2 for a description of each field on this 
screen.) 


S175 :NWSQOL-/DEMODATA/PATIENTS . DTA 
Hand les : 
Open Mode : Active Btrieve Users 





Page Size : 
Read-Only Flag : 
Record Locks MN 


Transaction Lock: N 








To update the list of active users, press Insert. 


Monitoring Btrieve Users with the User Information Option 


You can use the User Information option on the Available Options menu to do 
the following: 


¢ List all active Btrieve users 
¢ List the files that a specific user is accessing 


+ Delete a user's SPX connection to Btrieve 


Listing All Users 


To list all Btrieve users active on the current server, select User Information 
from the Available Options menu. 


The Btrieve Monitor utility displays a scrollable list of active Btrieve users: 


| Active Btrieve Users | 
GHERNAND 





MOMEARA 
NETWARE SQL 
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The utility identifies each active user based on user location, as follows: 


¢ If the user is located at a workstation, the utility displays the username 
(such as JDOE). 


+ Ifthe user is located at a local server, the utility displays either the 
process-supplied, two-character agent ID or the full name of the process 
(such as NetWare SQL). 


+ Ifthe user is located at a remote server, the utility displays either the 
process-supplied, two-character agent ID or the full name of the process 
(such as NetWare SQL) provided the utility can determine the full name. 


To update the list of active users, press Insert. 


To display information about a user, highlight the user and press Enter. A User 
Information screen similar to the following appears. For a description of each 
field that appears on this screen, refer to Table 2. 


Hand les : 
Comection Number: 7 


Task Number : z680 
Site > WS 
User Location : AEEEDDDD 000015E37DZD7 


Locks Used : O 
Locks Available : 20 
Records Read : 
Records Inserted : 
Records Deleted 
Records Updated 

Disk Accesses 

Cache Accesses 











Since the utility dynamically updates the statistics shown on this screen, you 
may notice the values changing as you view the screen. 
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Listing Files Accessed by a User 


While the User Information screen is displayed, you can press Enter to list all 
Btrieve files currently accessed by that user. A screen similar to the following 
appears. 


Active Btrieve Files 


SYS -AWSQL/DEMODATA/PATIENTS . DTA 


SYS :USERS/“GHERNAND/PROJECT . DAT 





To update the list of active Btrieve files, press Insert. 


Deleting User Connections 


Deleting a user's connection removes the user from the list of active Btrieve 
users and terminates the user's SPX connection to Btrieve. Use the following 
steps to delete a user's SPX connection: 


1. Select the User Information option on the Available Options menu. 


2. On the Active Btrieve Users screen, highlight the user connection that 
you want to delete, and press the Delete key. 


NOTE: If the Btrieve Monitor utility does not list a connection number for the user 
you want to delete, but the NetWare connection has been terminated, then a 
Btrieve session is still active for that user. You must restart the workstation that 
originated the Btrieve session to delete the user for that session. 


You can avoid this problem by ensuring that your application issues a Btrieve 
Reset operation to close active Btrieve files and release all resources held by the 
application. 


3. In the prompt box that appears, select Yes if you are sure you want to 
delete the specified user. Otherwise, select No or press Esc. 








Table 2 Active Resources and User Information Field Descriptions 
Field Description 
Cache Accesses Shows the number of times the user has made Btrieve calls that accessed the 


Btrieve cache buffers. 
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Field 


Description 





Connection 
Number 


Disk Accesses 


Handles 


Locks Available 


Locks Used 


Open Mode 





Displays the NetWare connection number of the process if the process originates 
at a workstation. If the process originates at a server, this column is empty. 


Shows the number of times the user has made Btrieve calls that required disk I/O. 


Shows the number of Btrieve handles the user has as a result of opening files. 
Btrieve creates a handle each time a user opens a file; therefore, a single user can 
have several handles for the same file. 


Indicates the total number of read locks available to the user. 


Indicates the number of locks that the user has explicitly requested. The number 
of locks in use varies, depending on whether the user is in a transaction, as 
follows: 


+ Ifthe user is outside a transaction, this number indicates the number of records 
that the user has explicitly locked. 


+ Ifthe user is inside a concurrent transaction, this number indicates the number 
of pages in the file that the user has explicitly locked. Although the user actually 
requests record locks, these are converted to page locks inside a concurrent 
transaction. Consequently, five record locks are shown as two page locks if the 
five records are stored on two pages. 


+ Ifthe user is inside an exclusive transaction or the user holds no locks, this 
number is zero. 


Indicates the mode used to open the file: 


Accelerated The application that opened the file has shared, read/write 
access. With Btrieve 6.x, Accelerated mode is equivalent to 
Normal mode unless the file is flagged transactional. 


Exclusive The application that opened the file has exclusive access. Other 
applications cannot open the file until the calling application closes 
it. 


Normal The application that opened the file has normal shared, read/write 
access. 
Read only The application that opened the file has read-only access; the 


application cannot modify the file. 
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Field 





Description 





Page Size 


Read-Only Flag 


Record Locks 


Records Deleted 
Records Inserted 
Records Read 

Records Updated 


Site 


Task Number 


Transaction Lock 


TTS Flag 


Indicates the page size (in bytes) of this file. (A page is the smallest unit of storage 
that Btrieve moves between main memory and the disk.) 


Indicates whether the file is flagged through NetWare as read only. 
Shows the lock status of the current record: 

s—Single-record lock outside a transactions 

S—Single-record lock within a transaction 

m—Multiple-record lock outside a transaction 

M—Multiple-record lock within a transaction 

N—No record locks 


Single-record locks allow a user to lock only one record at a time. Multiple-record 
locks allow a user to lock more than one record at a time. 


Number of records the user has deleted. 
Number of records the user has inserted. 
Number of records the user has read. 

Number of records the user has updated. 


Specifies the location of the user process, as follows: 
LS—Local server 
RS—Remote server 


WS—Workstation 


Contains the process-supplied task number if the process originates at the server, 
a MS Windows workstation, or an OS/2 workstation. If the process originates at a 
DOS workstation, this column contains the SPX socket number. 


Indicates whether the entire file is locked by a transaction. A transactional file lock 
exists only as long as the application that opened the file is processing a 
transaction. Y indicates the entire file is locked. N indicates the file is not locked. 


Indicates whether TTS™ is being used with the file. (For more information on TTS, 
refer to your NetWare documentation.) 
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Field Description 





User Location Identifies the user process, as follows: 


+ Ifthe user is located at a workstation, this column contains the network number 
and node address. 


+ Ifthe user is located at the server, this column contains the server name. 





Monitoring Resources with the Resource Usage Option 


The Resource Usage option on the Available Options menu shows you (in real 
time) the total resources in use by the Btrieve NLM since it was loaded. When 
you select this option, the Btrieve Monitor utility displays the Btrieve 
Resource Usage screen. 





Btrieve Resource Usage 


Btrieve Resource Usage Current Peak Maximum 
Files: 3 3 20 
Handles: 3 3 60 
Locks: 0 4 3196 
Transactions: 0 0 15 
Clients: 1 1 30 
Threads : o 1 





Since the utility dynamically updates the statistics shown on this screen, you 
may notice the totals changing as you view the screen. 


NOTE: The Current values on the Btrieve Resource Usage screen are cumulative 
from the time you enter the screen. 


Table 3 shows the field descriptions for the Resource Usage screen in 
alphabetic order. 
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Table 3 Resource Usage Field Descriptions 








Field Description Statistics 
Clients Number of Btrieve processes. Current Number of active Btrieve 
processes. 
A process can be a BSPXCOM Peak Highest number of processes 
thread representing a client, a simultaneously active since the 
Message Router thread Btrieve NLM was loaded. 
representing a client, or a client 
NLM on the present server. 
Maximum Value set for the Number of Remote 


Sessions configuration option. 
Files Number of active Btrieve files. Current Number of active Btrieve files. 


Peak Highest number of Btrieve files that 
have been open simultaneously 
since the Btrieve NLM was loaded. 


Maximum Value set for the Number of Open 
Files configuration option. 


Handles Number of handles issued for Current Number of active file handles. 
Btrieve files. 


Peak Highest number of handles used 
simultaneously since the Btrieve 
NLM was loaded. 


Maximum Value set for the Number of 
Handles configuration option. 


Locks Number of implicit (system) page Current Number of implicit active page 
locks involved in concurrent locks. 
transactions. 
Peak Highest number of implicit page 


locks used simultaneously since 
the Btrieve NLM was loaded. 


Maximum Maximum simultaneous page locks 
that the system will allow. 


Threads Number of programs or program Current Last system snapshot of active 
threads calling Btrieve programs or program threads 
simultaneously. calling Btrieve simultaneously. 
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Field Description Statistics 





Peak Maximum value ever encountered 
for the Current value since the NLM 
was loaded. 

Transactions Number of concurrent and Current Number of active concurrent and 
exclusive transactions. exclusive transactions. 

Peak Highest number of transactions 


active simultaneously since the 
Btrieve NLM was loaded. 


Maximum Value set for the Number of 
Transactions configuration option. 


Monitoring SPX Activity with the Communication Statistics Option 


The Communication Statistics option on the Available Options menu shows 
you (in real time) the network requests, packet buffers, and sessions in use for 
the communications module you have loaded. 


When you select this option, the Btrieve Monitor utility displays the 
Communications Statistics screen for BSPXCOM, BSPXSTUB, or 





RSPXSTUB. 

Btrieve Requests (Current, Total) : 0 0 

Concurrent Processes (Current, Max) : 0 3 

SPX Packet Buffers (Available, Max) : 200 ¿00 

Unprocessed SPX Packets (Current) : 0 

SPX Packets Received (Current, Total) 0 0 

SPX Packets Sent (Current, Total) 0 0 

SPX Requests Processed (Current, Total) 0 0 
SPX Sessions (Current, Max, Peak) 0 15 0 





The communication activity shown on this screen reflects the communication 
activity of the communications module loaded at your server: 


+ Ifyou loaded BSPXCOM, you see incoming and outgoing SPX statistics. 


¢ If you loaded BSPXSTUB, you see all zeros for the communication 
statistics. 
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+ If you loaded RSPXSTUB, you see incoming and outgoing SPX 
communication statistics from the Message Router. 


This screen does not show the communication activity of any remote NLMs. 


NOTE: The Total values shown on this screen are cumulative from the time Btrieve 
is loaded. The Current values are cumulative from the time you display the screen. 


Table 4 shows field descriptions for the Communication Statistics option, in 


alphabetic order. 








Table 4 Communication Statistics Field Descriptions 
Field Description Statistics 
Btrieve Number of network requests the Current Current value since the last screen 
Requests NLM has processed from update. 
workstations or remote server- 
based applications. 

Total The number of requests received since 

the Btrieve NLM was loaded. 
Concurrent Number of remote requests the Current Current value since the last screen 
Processes NLM processes at one time. update. 

Max The maximum number of remote 
clients the Btrieve NLM can process at 
one time. 

SPX Packet Number of SPX packet buffers Available Current number of available packet 
Buffers available to the NLM. buffers (as of the last screen update). 


SPX Packets 
Received 


SPX Packets 
Sent 


Max 


Number of SPX packets the Current 
NLM has received from 
applications. 


Total 


Number of SPX packets the Current 
NLM has sent to other 
applications. 


Value set for the maximum number of 
available packet buffers. Each session 
is allocated two packet buffers for 
Btrieve requests. 


Current value since the last screen 
update. 
The number of packets received since 


the communications NLM was loaded. 


Current value since the last screen 
update. 
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Field Description Statistics 





Total 


SPX Requests Number of SPX requests the Current 
Processed NLM has processed. 


Total 


SPX Sessions Number of remote clients who Current 
have established SPX sessions 
with the communications NLM. 


Max 
Peak 
Unprocessed Number of SPX packets the Current 
SPX Packets NLM has received but not yet 
processed. 


The number of packets sent since the 
communications NLM was loaded. The 
total packets sent may be larger than 
the total packets received because a 
single request received might produce 
several packets sent. 


Current value since the last screen 
update. 


The number of requests processed 
since the communications NLM was 
loaded. 


Current value since the 
communications NLM was loaded. 


Value set for the Number of Remote 
Sessions configuration option. 


Highest value since the 
communications NLM was loaded. 
This value indicates the highest 
number of SPX clients that have 
simultaneously had concurrent active 
sessions with the communications 
NLM. 


Current value since the last screen 
update. 
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Btrieve Maintenance Utility 


The Btrieve Maintenance utility (BUTIL.NLM) is a command line utility that 
allows you to create, manipulate, and recover Btrieve data files. It runs as an 
NLM at the server. You can access it at the server console or at a workstation 
through the RCONSOLE utility. You can execute the Maintenance utility 
commands from the server command line or from a command file. 


To run the Maintenance utility, be sure that the following are installed on your 
server: 


NetWare v3.12 
+ Btrieve v6.1 or later 


NOTE: Running Btrieve v6.1 in a NetWare v3.12 environment requires 
AFTER311.NLM, which Btrieve loads automatically. 


Utility Overview 


Command Format 





-command 


parameter 


commandFile 


This section provides information you need to know before using the 
Maintenance utility commands. It discusses the required command format, the 
concepts you should understand before running the Maintenance utility, and 
the use of command files. 


NOTE: If you have used the utility before, you may want to skip to the individual 
command discussions, which begin on “CLONE” on page 102. (The commands are 
discussed in alphabetic order.) 


The format for the Maintenance utility commands is as follows: 
LOAD BUTIL [-command [parameter ...]] | @commandFile 
A Maintenance utility command, such as COPY. You must precede the 


command with a dash (-), and you must enter a space before the dash. 
Table 5 


Information that the command may require. The discussions of the 
individual commands (beginning on “CLONE” on page 102 


Full pathname of a command file. 
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Table 5 Maintenance Utility Commands 








Command Description 

CLONE Creates a new, empty Btrieve file using an existing file's specifications. 
CLROWNER Clears the owner name of a Btrieve file. 

COPY Copies the contents of one Btrieve file to another. 

CREATE Creates a Btrieve file. 

DROP Drops an index. 

ENDBU Ends continuous operation on Btrieve files defined for backup. 

INDEX Creates an external index file. 

LOAD Loads the contents of a sequential file into a Btrieve file. 

RECOVER Reads data sequentially from a Btrieve file and writes the results to a sequential file. 
SALVAGE Examines a file's Page Allocation Table (PAT) to determine if corruption has occurred 


and if repair is required. 


SAVE Reads data along a key path and writes the results to a sequential file. 
SETOWNER Assigns an owner name to a Btrieve file. 

SINDEX Creates an index. 

STARTBU Starts continuous operation on files defined for backup. 

STAT Reports statistics about file attributes and current sizes of Btrieve files. 
VER Displays the version of the Btrieve NLM that is loaded at the server. 
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Concepts 


The following paragraphs describe concepts you should understand before 
using the Maintenance utility commands. 


Filenames 


The Maintenance utility runs as an NLM. The NLM environment does not 
recognize drive letters or environment variables. Thus, for commands that 
require a filename, the name must include the full pathname, such as 
SYS:\NWSQL\DEMODATA\PATIENTS.DTA. If you do not specify a 
volume, the utility assumes SYS: is the volume. 


Owner Names 


Btrieve allows you to restrict access to a file by specifying an owner name. 
Since owner names are optional, the files you use with this utility may or may 
not require an owner name. 


If the file requires an owner name, you must specify it using the /O option. 
(Alternatively, you can use a dash with this option, as in -O.) Owner names 
are case sensitive; that is, Sandy and SANDY are not considered to be the 
same. You can follow the /O option with an owner name or an asterisk (*). If 
you use an asterisk, the utility prompts you for an owner name. 


Description Files 


A description file is an ASCII file containing information that the 
Maintenance utility commands CREATE, INDEX, and SINDEX need to 
perform their operations. Description files contain one or more elements. 


An element consists of a keyword, followed by an equal sign (=), followed by 
a value (with no space separator). Each element in the description file 
corresponds to a particular characteristic of a Btrieve file or key definition. 
“Description Files” on page 137 provides more information. 


Continuous Operation 


Continuous operation is a Btrieve feature that allows you to back up files 
while they are in use by Btrieve applications. Two Maintenance utility 
commands, STARTBU and ENDBU, begin and end continuous operation on 
a file or set of files. 


When continuous operation begins, Btrieve creates a temporary Btrieve file 
(called a delta file) for each data file in order to record any changes made to 
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Command Files 


the data file while the backup is taking place. This temporary delta file may 
surpass the size of the original data file if users make extensive changes to the 
file during continuous operation. 


When continuous operation ends, Btrieve updates the master Btrieve files with 
the changes stored in the delta files. Btrieve deletes the delta files as soon as 
all applications close the corresponding Btrieve data files. 


NOTE: As indicated above, when you place a Btrieve file into continuous operation 
mode, Btrieve creates a temporary delta file with the same name as the data file 
but with a .^^^ extension. Therefore, do not create multiple Btrieve files with the 
same names but different extensions. For example, do not use a naming scheme 
such as INVOICE.HDR and INVOICE.DET for your Btrieve files. 


To back up files using continuous operation, first issue the BUTIL -STARTBU 
command, followed by the file or set of files. Next, run your backup program. 
To stop continuous operation, issue the BUTIL -ENDBU command. 


HINT: The best time to place Btrieve data files into continuous operation for 
backup is when the fewest users will be making modifications to the files. 


You can use a command file to do either of the following: 
+ Execute a command that is too long to fit on the command line 


+ Execute a command that you use often (by entering the command once in 
the command file and then executing the command file as often as you 
want) 


Command files contain the same information as that required on the command 
line. 


Rules for Command Files 


Observe the following rules when creating a Maintenance utility command 
file: 


+ You must limit each line to 130 characters. 


NOTE: Lines longer than 130 characters could cause the server to end 
abnormally. For this reason, do not place long Maintenance utility commands in a 
server command (.NCF) file. 


+ You cannot split a single parameter across two lines. 


+ You can specify only one command per command file. 
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Command File Example 


The following is an example command file, COPYPATS.CMD. The file calls 
the BUTIL -CLONE command to clone the file PATIENTS.DTA. 


-clone sys:\nwsql\demodata\allpats.dta 
sys: \nwsql\demodata\patients.dta 


The following command uses the COPYPATS.CMD file: 


load butil @sys:\nwsql\demodata\copypats.cmd 


Maintenance Utility Commands 


This section describes the Maintenance utility commands and explains when 
and how to use each one. 


At any time while using the Maintenance utility commands, you can enter 
LOAD BUTIL to see the Maintenance utility commands. The utility responds 
with the following screen. 





The command syntax is as follows: 

BUTIL -CLONE <outputBtrieveFile> <sourceBtrieveFile> [/O<owner1>] 

BUTIL -CLROWNER <btrieveFile> </O<owner>> 

BUTIL @commandFile 

BUTIL -COPY <inputBtrieveFile> <outputBtrieveFile> C-O<owner1> 
[/O<owner2> 1] 

BUTIL -CREATE <btrieveFile> <descriptionFile> 

BUTIL -DROP <btrieveFile> <keyNumber> [/0<ouner>1] 

BUTIL -ENDBU [<btrieveFile> | <@fileName>] 

BUTIL -INDEX <btrieveFile> <indexFile> <descriptionFile> [/O<owner>] 

BUTIL -LOAD <inputFile> <btrieveFile> [/O<ouner>1] 

BUTIL -RECOVER <btrieveFile> <outputFile> [-0O<owner> 1] 

BUTIL -SALVAGE <btrieveFile> [-«0O<owner>1 

BUTIL -SAVE <btrieveFile> <outputFile> CY indexFile i N keyNumber] 
[/O<owner > J 

BUTIL -SETOWNER <btrieveFile> </O<owner>> <level> 

BUTIL —-SINDEX <btrieveFile> <descriptionFile> [-O<ouner>]1 

BUTIL -STARTBU <btrieveFile> | <@listFile> 

BUTIL -STAT <btrieveFile> [-O<owner>] 

BUTIL -VER 
<Press any key to continue? 
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CLONE 


The CLONE command creates a new, empty Btrieve file with the same file 
specifications as an existing file (including any supplemental indexes, but 
excluding the owner name). The new Btrieve file includes all the defined key 
characteristics (such as key position, key length, or duplicate key values) 
contained in the existing file. 


Format 


LOAD BUTIL -CLONE outputBtrvFile sourceBtrvFile [/Oowner] 


outputBtrvFile The full pathname you want to use for the new, empty Btrieve file. 
sourceBtrvFile The full pathname of the existing Btrieve file that you want to replicate. 
owner The owner name, if any, for the source Btrieve file. The new Btrieve file will 


not have an owner name. 





Remarks 


Btrieve v6.x allows a maximum of 23 key segments in a Btrieve file with a 
page size of 1,024 bytes. Therefore, the CLONE command sets the page size 
in the new Btrieve file to 2,048 bytes if the existing Btrieve file contains 24 
key segments and has a page size of 1,024 bytes. This occurs if the existing 
Btrieve file has a format earlier than Btrieve v6.0 and the Btrieve NLM was 
not loaded with the Create Btrieve Files in Pre v6.x Format configuration 
option. 


Example 


The following command creates the NEWAPP.DTA file by cloning the 
PATIENTS.DTA file. 


load butil -clone sys:\nwsql\demodata\newapp.dta 
sys: \nwsql\demodata\patients.dta 


HINT: If you are trying to recover from receiving Status Code 30 and you suspect 
that the header page of the source file might be damaged, try creating the new 
Btrieve file by using the BUTIL -CREATE command with a description file. 
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CLROWNER 


The CLROWNER command clears the owner name of a Btrieve file. 


Format 


LOAD BUTIL -CLROWNER btrvFile /Oowner 








btrvFile The full pathname of the Btrieve file. 
owner The owner name to be cleared. 
Example 


The following command clears the owner name for the PATIENT 1.DTA file. 
The owner name for the file is Sandy. 


load butil -clrowner sys: \nwsql\demodata\patient1.dta /OSandy 


COPY 


The COPY command copies the contents of one Btrieve file to another. COPY 
retrieves each record in the input Btrieve file and inserts it into the output 
Btrieve file. The record size must be the same in both files. After copying the 
records, COPY displays the total number of records inserted into the new 
Btrieve file. 


NOTE: COPY performs in a single step the same function as a RECOVER 
command followed by a LOAD command. 


By using the COPY command, you can create a Btrieve file that contains data from 
an old file, but has new key characteristics. To do so, proceed as follows: 


1. Use the CREATE command to create an empty Btrieve file with the 
desired key characteristics (key position, key length, or duplicate key 
values). 


2. Use the COPY command to copy the contents of the existing Btrieve file 
into the newly created Btrieve file. 
Format 


LOAD BUTIL -COPY inputBtrvFile outputBtrvFile [/Oownerl 
[/Oowner2] ] 
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inputBtrvFile The full pathname of the Btrieve file from which you want to transfer 
records. 


outputBtrvFile The full pathname of the Btrieve file into which you want to insert records. 
The output Btrieve file can contain data or be empty. 


owner1 The owner name of the input Btrieve file, if required. If only the output 
Btrieve file requires an owner name, specify /O followed by a blank for 
owner? (as illustrated in the example). 


owner2 The owner name of the output Btrieve file, if required. 





Example 


The following command copies the records in PATIENTS.DTA to 
NEWPATS.DTA. The PATIENTS.DTA input file does not require an owner 
name, but the NEWPATS.DTA output file uses the owner name Pam. 


load butil -copy sys:\nwsql\demodata\patients.dta 
sys: \nwsql\demodata\newpats.dta /O /OPam 


If you omit the first /O from this example, the utility assumes that the owner 
name Pam belongs to the input Btrieve file, not the output Btrieve file. 


CREATE 


The CREATE command generates an empty Btrieve file using the 
characteristics you specify in a description file. 


Before you can use the CREATE command, you must create a description file 
to specify the new key characteristics. For more information, see “Description 
Files” on page 137. 

Format 


LOAD BUTIL -CREATE btrvFile descriptionFile 





btrvFile The full pathname of the Btrieve file you want to create. If the pathname is 
the name of an existing Btrieve file, this command creates a new, empty 
Btrieve file in place of the existing Btrieve file. Any data that was stored in 
the existing Btrieve file is lost and cannot be recovered. However, Btrieve 
does not create a new Btrieve file if you specify replace=n in the description 
file. (For an example, see “Replace Existing File” on page 147.) 
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descriptionFile 


The full pathname of the description file containing the specifications for the 


new Btrieve file. 


Example 


The following command creates a Btrieve file named PATIENTS.DTA using 


the description provided in the BUILD.DES description file. 


load butil -create sys:\nwsql\patients.dta 
sys: \nwsql\build.des 


Sample Description File for the CREATE Command 


The sample description file shown in the following illustration creates a 


Btrieve file. The Btrieve file is specified to have a page size of 512 bytes and 
2 keys. The fixed-length portion of each record in the Btrieve file is set to 98 


bytes. Variable-length records with no blank truncation, data compression, 
and Variable-tail Allocation Tables (VATs) are specified. The free space 
threshold is set to 20 percent. Allocation is set to 100 pages. Btrieve will 
preallocate 100 pages, or 51,200 bytes, when it creates the Btrieve file. 


record=96 variable=y truncate=n conpress-y File 

key=2 page=512 allocation=100 replace=n | ee 
fthreshold-20 huge-y Specificaions 
position=1 length=5 duplicates-y Key 0 
nodifiable=n type=string altermate=y Segment 1 
mull=y value=20 seqment=y 

position=6 length=10 duplicates-y Key 0 
nodifiable=n type=string alternate=y Segment 2 
mil="r value=20 seqment=n 

position=16 length=2 duplicates=n 

modifiable=y type=numeric descending=y Key 1 
alternate=n null=n seqnent=n 

name=patA/upper.alt 











Key 0 is a segmented key with two duplicatable, nonmodifiable string 
segments and a null value of 20 hexadecimal (space) specified for both 
segments. Key 0 uses the collating sequence UPPER.ALT. 


Key 1 is a numeric, nonsegmented key that does not allow duplicates but 
permits modification. It is sorted in descending order. 
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DROP 


btrvFile 


keyNumber 


owner 


The DROP command removes an index from a Btrieve file and adjusts the key 
numbers of any remaining indexes, subtracting | from each subsequent key 
number. If you do not want to renumber the keys, you can add 128 to the key 
number you specify to be dropped. This renumbering feature is available only 
for Btrieve v6.x files. 

Format 


LOAD BUTIL -DROP btrvFile keyNumber [/Oowner] 


The full pathname of the Btrieve file from which you are dropping the index. 


The number of the index you want to remove. If you want to preserve the 
original key numbers, add a 128 bias to the key number you specify. 


The owner name for the Btrieve file, if required. 





Examples 


In both of the following examples, PATIENTS.DTA has three keys. The 
original keys in the file were numbered 0, 1, and 2. 


In the first example, the BUTIL -DROP command drops key number | from 
the PATIENTS.DTA file and renumbers the remaining key numbers as 0 and 
1. 


load butil -drop sys:\nwsql\demodata\patients.dta 1 


In the following example, the BUTIL -DROP command drops key number 1 
and does not renumber the keys. The key numbers remain 0 and 2. 


load butil -drop sys:\nwsql\demodata\patients.dta 129 
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ENDBU 


btrvFile 


@filename 


The ENDBU command ends continuous operation on a Btrieve file or set of 
Btrieve files previously defined for backup. Execute this command after you 
have issued the STARTBU command and your backup utility has finished 
running. (For more information on the STARTBU command, see 
“STARTBU” on page 118. For more information on continuous operation, see 
“Continuous Operation” on page 99.) 


To back up Btrieve files using continuous operation, first issue the LOAD 
BUTIL -STARTBU command, followed by the Btrieve file or set of Btrieve 
files. Next, run your backup program. Then, stop continuous operation by 
issuing the LOAD BUTIL -ENDBU command. 


NOTE: When you place a Btrieve file into continuous operation mode, Btrieve 
creates a temporary delta file with the same name as the Btrieve data file, but with 
a “MM extension. Therefore, do not create multiple Btrieve files with the same 
names but different extensions. For example, do not use a naming scheme such 
as INVOICE.HDR and INVOICE.DET for your Btrieve files. 


Format 


LOAD BUTIL -ENDBU [btrvFile | @filename] 


The full pathname of the Btrieve file for which you want to end continuous operation. 


The name of a text file containing a list of Btrieve files for which you want to end 
continuous operation. The text file must contain the full pathname for each Btrieve 
file, and you must separate these pathnames with a space or a carriage return/line 
feed. Typically, this list of Btrieve files is the same as the list used with the STARTBU 
command. 





If you do not specify any Btrieve files with the LOAD BUTIL -ENDBU 
command, the utility stops continuous operation on all Btrieve files initialized 
by BUTIL -STARTBU and currently running in continuous operation mode. 


Example 


The following example ends continuous operation on the PATIENTS.DTA 
file. 


load butil -endbu sys:\nwsql\demodata\patients.dta 
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INDEX 


The INDEX command builds an external index file for an existing Btrieve file, 
based on a field not previously specified as a key in the existing file. Before 
you can use the INDEX command, you must create a description file to 
specify the new key characteristics. (For more information on description 
files, see “Description Files” on page 137.) 


The external index file created is a key-only Btrieve file. The records in the 
new file consist of the following: 


+ The 4-byte address of each record in the existing Btrieve file 
+ The new key value on which you want to sort 
NOTE: If the key length you specify in the description file is 10 bytes, the record 
length of the external index file would be 14 bytes (10 plus the 4-byte address). 
Format 


LOAD BUTIL -INDEX btrvFile indexFile descriptionFile [/ 
Oowner] 





btrvFile 


indexFile 


descriptionFile 


owner 


The full pathname of the existing Btrieve file for which you want to build an 
external index. 


The full pathname of the index file in which Btrieve should store the external 
index. 


The full pathname of the description file you have created containing the 
new key definition. The description file should contain a definition for each 
segment of the new key. 


The owner name for the Btrieve file, if required. 





Remarks 


The INDEX command creates the external index file and then displays the 
number of records that were indexed. If you want to retrieve the Btrieve file's 
records using the external index file, use the SAVE command (described in 
“SAVE” on page 115). 


Sample Description File for the INDEX Command 


The description file shown in the following illustration defines a new key with 
one segment. The key begins at byte 30 of the record and is 10 bytes long. It 
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LOAD 


allows duplicates, is modifiable, is a string type, and uses no alternate 
collating sequence. 





position=30 length=10 duplicates=y modifi able-y 
type=string alternate=n seqment=n 





Example 


The following command creates an external index file called NEWPAT.IDX 
using a Btrieve file called PATIENTS.DTA. The PATIENTS.DTA file does 
not require an owner name. The description file containing the definition for 
the new key is called NEWIDX.DES. 


load butil -index sys:\nwsql\demodata\patients.dta 
sys: \nwsql\demodata\newpat .idx 
sys: \nwsql\demodata\newidx.des 


NOTE: When you place a Btrieve file into continuous operation mode, Btrieve 
creates a temporary delta file with the same name as the data file, but with a ^^^ 
extension. Therefore, do not create multiple Btrieve files with the same names but 
different extensions. For example, do not use a naming scheme such as 
INVOICE.HDR and INVOICE.DET for your Btrieve files. 


The LOAD command inserts records from an input sequential file into a 
Btrieve file. LOAD performs no conversion on the data in the input sequential 
file. After the utility transfers the records to the Btrieve file, it displays the 
total number of records loaded. 


Before running the LOAD command, you must create the input sequential file 
and the Btrieve file. You can create the input sequential file using a standard 
text editor or an application; the input sequential file must have the required 
file format (as explained subsequently). You can create the Btrieve file using 
either the “CREATE” on page 104 or the “CLONE” on page 102 command 
(BUTIL -CREATE or BUTIL -CLONE). 


Format 


LOAD BUTIL -LOAD inputFile btrvFile [/Oowner] 
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inputFile The full pathname of the ASCII sequential file containing the records to be loaded 
into a Btrieve file. 


btrvFile The full pathname of the Btrieve file into which you want to insert the records. 


owner The owner name for the Btrieve file, if required. 





Required File Format 


Records in the input sequential file must be in the following format: 


+ 


+ 


+ 


+ 


The first field must be a left-adjusted integer (in ASCII) that provides the 
length of the record. This field does not include the carriage return or line 
feed. 


For files with fixed-length records, the length you specify should equal 
the record length of the Btrieve file. 


For files with variable-length records, the length you specify must be at 
least as long as the minimum fixed length of the Btrieve file. 


A separator (either a comma or a blank) must follow the length field. 


The record data follows the separator. The length of the data must be the 
exact number of bytes specified by the length field. 


A carriage return/line feed (ODOA hexadecimal) must terminate each line. 
The carriage return/line feed is not included in the length value at the 
beginning of the line, and LOAD does not insert the carriage return/line 
feed into the Btrieve file. 


The last line in the file must consist of the end-of-file character (Ctrl+Z 
or 1A hexadecimal). The SAVE and RECOVER commands and most text 
editors automatically insert this character in the file. 


You can create an input sequential file using either a text editor or an 
application, as follows: 


+ 


If you use a text editor to create the input sequential file, pad each record 
with blank spaces as necessary to fill the record to the length you 
specified at the beginning of the record. Fields containing binary data 
cannot be edited with most text editors. 


If you use an application to create the input sequential file, append a 
carriage return/line feed to the end of each record and include an end-of- 
file character (Ctrl+Z or 1A hexadecimal) as the last line in the file. The 
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sequential I/O calls provided by most high-level language processors 
insert carriage return, line feed, and end-of-file characters automatically. 


The following illustration shows the correct format for records in the input 
sequential file. For this example, the Btrieve file has a defined record length 
of 40 bytes. 





40, The record follows the comma delimiter <CK/LF> 


à ~oo] 
Data 


Carriage Return 
or Lino Food 


Comma Delimiter 





Record Length Blank Pad 
for P-oper Length 











Example 


The following example loads sequential records from the PATIENTS.ADR 
file into the PATIENTS.DTA file. The owner name of the PATIENTS.ADR 
file is Sandy. 


load butil -load sys:\nwsql\demodata\patients.adr 
sys: \nwsql\demodata\patients.dta /OSandy 
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RECOVER 


The RECOVER command extracts data from a Btrieve file and places it in a 
sequential file that has the same format as the input sequential file used by the 
LOAD command. This is often useful for extracting some or all of the data 
from a damaged Btrieve file. The RECOVER command may be able to 
retrieve many, if not all, of the file's records. You can then use the LOAD 
command to insert the recovered records into a new, undamaged Btrieve file. 


NOTE: The Maintenance utility performs no conversion on the data in the records. 
Therefore, if you use a text editor to modify an output file containing binary data, be 
aware that some text editors may change the binary data, causing the results to be 
unpredictable. 


The RECOVER command performs the following actions: 


+ Checks the file's Page Allocation Table (PAT) and reconstructs it, if users 
request this. The PAT is the part of the Btrieve file that maintains a map 
of each page's physical location. 


+ Reads records in physical order from the Btrieve file, using Btrieve Step 
operations. 


+ Creates a sequential file that is compatible with the required format for 
the LOAD command. (See “Required File Format” on page 110 for more 
information about the format.) 


¢ Displays the total number of recovered records. 


Format 


LOAD BUTIL -RECOVER btrvFile outputFile [/Oowner] 








btrvFile The full pathname of the Btrieve file from which you want to recover data. 
outputFile The full pathname of the ASCII sequential file where the utility should store the 
recovered records. 
owner The owner name for the Btrieve file, if required. 
Remarks 


If the file's PAT is damaged, a prompt similar to the following appears: 


The file's Page Allocation Table seems to be damaged.BUTIL 
*strongly* recommends that you make a backup copy before 
continuing.Continue? 1=Yes 2=No 
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By default, the prompt displays 2 (indicating No) on the next line. This allows 
you to exit the RECOVER command and back up the Btrieve file before 
proceeding. If you have already backed up the Btrieve file, enter 1 to continue 
running the RECOVER command. 


The RECOVER command allows you to set the Btrieve file's page size. It 
displays the following prompt: 


Enter the page size or 0 to quit: 512 


The value displayed at this prompt is the result of an attempt to determine the 
original page size of the Btrieve file. If this value is incorrect, enter the correct 
page size. If you enter a page size that differs from the original page size, the 
result is unpredictable. If you are unsure of the correct page size, change the 
value as prompted by the utility. 


If the logical disk drive containing your output sequential file becomes full 
before the entire Btrieve file has been recovered, the utility stops, indicates the 
number of records already recovered, and displays the following prompt: 


The disk volume is full.Enter new file name to continue or a 
period to quit. 


To continue running the RECOVER command using an additional output 
sequential file, complete one of the following steps: 


+ Ifyou are recovering the Btrieve file to diskettes, remove the full diskette 
and replace it with another formatted diskette. 


¢ If you are recovering the Btrieve file to a hard disk, specify another 
logical disk drive that has space available. 


In either case, enter the full pathname of the Btrieve file you want to use to 
continue storing records, and then press the Enter key. The utility continues 
copying records from the Btrieve file to the new output sequential file. This 
process creates multiple sequential files that you must load separately with the 
LOAD command. 


If the RECOVER command receives a variable page error (Status Code 54), 
it places all the data it can obtain from the current record in the output 
sequential file and continues the recovery process. 


Upon completion, the utility displays a message similar to the following: 


16 records recovered.Operation completed successfully. 
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SALVAGE 


Example 


The following example extracts records from the PATIENTS.DTA file and 
writes them into the SEQPAT.DAT file. 


load butil -recover sys:\nwsql\patients.dta 
sys: \nwsql\seqpat.dat 


The SALVAGE command examines the records in a file's PAT to determine if 
corruption has occurred. (The PAT maintains a map of the physical location of 
each page in the Btrieve file.) If corruption has occurred, the utility asks if you 
want to repair the PAT. 


Format 


LOAD BUTIL -SALVAGE btrvFile [/Oowner] 





btrvFile 


owner 


The full pathname of the Btrieve file containing the records you want to check. 


The owner name for the Btrieve file, if required. 





Remarks 


If the file's PAT is damaged, the utility reminds you that you should have a 
backup of the Btrieve file before proceeding and asks if you want to repair the 
file now. If you have already backed up the Btrieve file, enter Y (for Yes). If 
you have not backed up the Btrieve file, enter N (for No). 


After you enter Y, the utility asks you to enter a page size and provides you 
with the result of its attempt to determine the original page size. If you suspect 
that the value shown is incorrect, enter a new value. The utility then attempts 
to repair the Btrieve file, using the new value. If the utility cannot repair the 
Btrieve file, it sends a message identifying the reason why. 


NOTE: The SALVAGE command does not save the records to a sequential file. 
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SAVE 


btrvFile 


outputFile 


indexFile 


keyNumber 


owner 


The SAVE command retrieves records from a Btrieve file using a specified 
index path and places them in a sequential file that is compatible with the 
required format for the LOAD command. You can then edit the sequential file 
and use the LOAD command to store the edited data in another Btrieve file. 
(See “LOAD” on page 109 for more information about LOAD.) 


SAVE generates a single record in the output sequential file for each record in 
the input Btrieve file. Upon completion, SAVE displays the total number of 
records saved. 


NOTE: The Maintenance utility performs no conversion on the data in the records. 
Therefore, if you use a text editor to modify an output file containing binary data, be 
aware that some text editors may change the binary data, causing the results to be 
unpredictable. 


Format 


LOAD BUTIL -SAVE btrvFile outputFile [Y indexFile | N 
keyNumber] [/Oowner] 





The full pathname of the Btrieve file containing the records you want to save. 


The full pathname of the ASCII sequential file in which you want the utility to 
store the records. 


The full pathname of an external index file by which you want to save records if 
you do not want to save records using the default of the lowest key number. 


The key number (other than 0) by which you want to save records if you do not 
want to save records using the default of the lowest key number. 


The owner name for the Btrieve file, if required. 





Remarks 


If the logical disk drive containing your output sequential file becomes full 
before the entire Btrieve file has been saved, the utility stops, indicates the 
number of records already saved, and displays the following message: 


The disk volume is full.Enter new file name to continue or a 
period to quit. 


To continue the SAVE operation in another output sequential file, complete 
one of the following steps: 
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¢ Ifyou are saving the Btrieve file to diskettes, remove the full diskette and 
replace it with another formatted diskette. 


¢ If you are saving the Btrieve file to a hard disk, specify another logical 
disk drive that has space available. 


In either case, enter the full pathname of the Btrieve file you want to use to 
continue storing records, and press the Enter key. The utility continues 
copying records from the Btrieve file to the new output sequential file. Keep 
in mind that this process creates multiple sequential files that you must load 
separately with the LOAD command. 


Examples 


The following two examples illustrate how to use the SAVE command to 
retrieve records from a Btrieve file. 


The first example uses the NEWPAT.IDX external index file to retrieve 
records from the PATIENTS.DTA file and store them in an unformatted text 
file called PATIENTS.SAV: 


load butil -save sys:\nwsql\demodata\patients.dta 
sys: \nwsql\demodata\patients.sav 
sys: \nwsql\demodata\newpat .idx 


The next example retrieves records from the PATIENTS.DTA file using key 
number 3 and stores them in an unformatted text file called PATIENTS.SAV: 


load butil -save sys:\nwsql\demodata\patients.dta 
sys: \nwsql\demodata\patients.sav N 3 
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SETOWNER 


The SETOWNER command creates an owner for a Btrieve file. 


Format 


LOAD BUTIL -SETOWNER btrvFile /Oowner level 





btrvFile The full pathname of the Btrieve file. 
owner The owner name to be set. 
level The type of access restriction for the Btrieve file. The possible values for this parameter 


are as follows: 

O Requires an owner name for any access mode (no data encryption) 

1 Permits read access without an owner name (no data encryption) 

2 Requires an owner name for any access mode (with data encryption) 


3 Permits read access without an owner name (with data encryption) 





Example 


The following example creates an owner for the PATIENTS.DTA file. The 
owner name is Sandy, and the restriction level is 1. 


load butil -setowner sys: \nwsql\demodata\patients.dta /OSandy 
1 


SINDEX 


The SINDEX command creates an additional index for an existing Btrieve 
file. The key number of the new index is one higher than the previous highest 
key number for the Btrieve file. An exception is if a DROP command 
previously removed an index without renumbering the remaining keys, thus 
producing an unused key number; in this case, the new index receives the first 
unused number. 


Before you can use the SINDEX command, you must create a description file 
to define key specifications for the index. For more information on description 
files, see Appendix A. 


Format 


LOAD BUTIL -SINDEX btrvFile descriptionFile [/Oowner] 
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btrvFile 


descriptionFile 


owner 


The full pathname of the Btrieve file for which you are creating the index. 


The full pathname of the description file containing the description of the 
index you want to create. 


The owner name for the Btrieve file, if required. 





STARTBU 


Examples 


The following example adds an index to the PATIENTS.DTA file. The name 
of the description file is SUPPIDX.DES. 


load butil -sindex sys:\nwsql\demodata\patients.dta 
sys: \nwsql\suppidx.des 


The STARTBU command places a file or set of files into continuous operation 
for backup purposes. 


To back up files using continuous operation, first issue the LOAD BUTIL - 
STARTBU command, followed by the Btrieve file or set of Btrieve files. Next, 
run your backup program. Then, issue the LOAD BUTIL -ENDBU command 
to stop continuous operation. For more information on the ENDBU command, 
see “ENDBU” on page 107. For more information on continuous operation, 
see “Continuous Operation” on page 99. 


HINT: When you place a Btrieve file into continuous operation mode, Btrieve 
creates a temporary file with the same name as the data file, but with a ^^^ 
extension. Therefore, do not create multiple Btrieve files with the same names but 
different extensions. For example, do not use a naming scheme such as 
INVOICE.HDR and INVOICE.DET for your Btrieve files. 


Format 


LOAD BUTIL -STARTBU <btrvFile | @filename> 





btrvFile 


@filename 


The full pathname of the Btrieve file on which to begin continuous operation for 
backup. 


The name of a text file containing the full pathnames of files on which to begin 
continuous operation. Separate these pathnames with a space or a carriage return/ 
line feed. 
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STAT 


btrvFile 


owner 


IMPORTANT: This command begins continuous operation only on the files you 
specify. You cannot use wildcards with the STARTBU command. 


Example 


The following example starts continuous operation on the PATIENTS.DTA 
file. 


load butil -startbu sys: \nwsql\demodata\patients.dta 


The STAT command reports the defined characteristics of a Btrieve file and 
statistics about the file's contents. 


Format 


LOAD BUTIL -STAT btrvFile [/Oowner] 


The full pathname of the Btrieve file for which you want to display statistics. 


The owner name for the Btrieve file, if required. 


Example 


The following example retrieves the file statistics for the PATIENTS.DTA 
file. The Btrieve file does not have an owner name. 


load butil -stat sys:\system\515\patients.dta 
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The following illustration shows the resulting output screen: 








File Statistics for sys:Snusq]\demodata\patients .dta 
Record Length = 104 
Compressed Records = No 


Variable Records 
Number of Keys = 
Page Size = 2046 


Unused Pages = 0 


3 


Total Records = 16 


File Version = 60 


Key 
Position 
0 zi 
0 ? 
1 1 
É 83 


= No 
Length Modifiable Null 
Duplicates Type Total 
20 Y Y = String == 16 
12 Y Y = String == 16 
6 N Y «0 String — 16 
10 Y Y = String — 7 


+ 0 The Alternate Collating Sequence is UPPER 


The command completed successfully. 


<Press any key to 





continue? 


This example shows that the file called PATIENTS.DTA was defined with a 
record length of 104 bytes, does not allow variable-length records, has 3 keys, 
and has a page size of 2,048 bytes. Sixteen records have been inserted into the 
file. The file does not use data compression and is using all its preallocated 


pages. 


The Btrieve file version is 6.0. (If you created the Btrieve file with VATs or 
multiple alternate collating sequences, the STAT command displays file 
version 6.1. Otherwise, it displays file version 6.0.) 


NOTE: The STAT command designates case-insensitive keys and key segments 
with the letter |, descending keys with the symbol <, manual keys with the letter M, 
alternate collating sequence keys with an asterisk (*), and repeating-duplicatable 
keys with the letter R. Indexes created with SINDEX are also designated with the 
letter R by default unless you specified the Reserved Duplicate Pointer element. 
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VER 


The remainder of the screen provides information about specific keys. For 
example, the screen shows that Key 0 allows duplicates, is modifiable, and 
consists of two segments: 


¢ The first segment starts in position 21, is 20 characters long, allows 
duplicates, is modifiable, and will be sorted as a string type. The 
dashes indicate that a null value was not defined. The Total column 
indicates that 16 unique key values were inserted for this key. 


+ The second segment starts in position 7, is 12 characters long, allows 
duplicates, is modifiable, and will be sorted as a string type. Sixteen 
unique key values were inserted for this key. 


Key 1 consists of one segment. It starts in position 1, is 6 characters long, does 
not allow duplicates, is modifiable, and will be sorted as a string type. 
Sixteen unique key values were inserted for this key. 


Key 2 consists of one segment. It starts in position 83, is 10 characters long, 
allows duplicates, is modifiable, and will be sorted as a string type. Seven 
unique key values were inserted for this key. 


NOTE: The STAT command handles indexes the same whether they were created 
by the Btrieve Create Supplemental Index operation (in Btrieve v6.x) or the Btrieve 
Create operation. The information displayed by the STAT command does not 
differentiate between these indexes. 


The VER command returns the version number of the Btrieve NLM loaded at 
the server. 


Format 
LOAD BUTIL -VER 
Remarks 


When you run the VER command, the utility displays messages similar to the 
following: 


Btrieve Version is 6.1 NLM.Operation completed successfully. 
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Roll Forward Utility 


The Roll Forward utility is a workstation utility that recovers changes made to 
a Btrieve file between the time of the last backup and a system failure. The 
changes are stored in a log file. If a system failure occurs, you can restore the 
backup copy of your Btrieve file and run the Roll Forward utility. The utility 
applies the changes stored in the log file to your backup copy. 


Roll Forward utilities are available for DOS, OS/2, and Windows operating 
environments, as follows: 


+ BROLLFWD.EXE—The Roll Forward utility for the DOS operating 
environment. You run BROLLFWD from the command line. 


+ PBROLL.EXE—The Roll Forward utility for the OS/2 environment. You 
run PBROLL interactively. 


+ WBROLL.EXE—The Roll Forward utility for the Windows 
environment. You run WBROLL interactively. 


NOTE: The procedure for running PBROLL and WBROLL is the same. 


Setting Up Files for Logging 


To take advantage of Btrieve's logging feature and the Roll Forward utility, 
you must first set up your Btrieve files for logging, as follows: 


1. Activate Btrieve's logging configuration option (using the Setup utility, 
BSETUP.NLM). 


2. Create the log configuration file, BLOG.CFG. 
3. Back up your data files before the logging begins. 


The following sections explain each step. 


Activating the Btrieve Logging Option 


You can activate Btrieve's logging feature by specifying Yes for the Logging 
of Selected Files configuration option in the Setup utility. The default setting 
for this option is No. If you did not specify Yes for this option when you 

configured Btrieve, complete the following steps to activate Btrieve logging: 


1. Run the Setup utility (BSETUP.NLM). 


2. When the Available Options menu appears, select Set Btrieve 
Configuration. 
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3. When the Current Btrieve Configuration screen appears, specify Yes for 
the Logging of Selected Files option. 


4. Press the Escape key. 
5. When the Save Configuration Changes? window appears, select Yes. 


6. To have your changes take effect, unload Btrieve using the BSTOP 
command and then reload it using the BSTART command. Btrieve 
reloads with the logging feature activated. 


Creating the Log Configuration File 


BLOG.CFG is the log configuration file. It specifies all Btrieve files for which 
you want to log changes on a given volume. 


You should create a BLOG directory at the root of each volume that contains 
Btrieve files for which you want to log changes. You can then create a 
BLOG.CFG file in each BLOG directory and place entries in it, as follows: 


1. Create the BLOG.CFG file. 
2. Open the BLOG.CFG file. 


3. For each Btrieve file for which you want to log operations, create an entry 
using the following format: 


\directoryl1\btrvFile[=\directory2\logFile] 





directory1 The path to the Btrieve file to be logged. 


NOTE: Do not include server names, volume names, or DOS drive letters. 





btrvFile The name of the Btrieve file to be logged. 


directory2 The path to the log file. If the log file and the Btrieve file are on the same volume, 
you can omit the server and volume names. If they are on different volumes, you 
must include the server and volume names. 





NOTE: When including the server name, place a double backslash (\\) before it. 


logFile The name of the log file. Although the log file and the Btrieve file can be on different 
volumes, they cannot be on different servers. 
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Backing Up Data Files 


Make sure each entry fits completely on one line. You can place multiple 
entries on the same line, but they must be separated by at least one space. 
Each line can contain a maximum of 256 characters. 


If you do not provide a log name, Btrieve (at the time the file is first 
opened) assigns the original filename to the log file and gives ita .LOG 
extension. 


For example, if you did not specify a log name for the Btrieve file 
TESTO1.DAT in the directory TEST, Btrieve would assign the full name 
1TESTTESTO1.LOG to the associated log file. In this case, the default 
log file shares the same directory as the Btrieve file. 


The next three examples show sample entries in the file 
\BLOG\BLOG.CFG on the SYS: volume of the CORP server. Each of 
these entries causes activity in the file \DATA\B.BTR on the CORP 
server's SYS: volume to be logged into the file \DATA\B.LOG on the 
CORP server's SYS: volume. 


\data\b.btr 
\data\b.btr=\data\b.log 
\data\b.btr=\\corp\sys:\data\b.log 


The next example (again, a sample entry in BLOGBLOG.CFG on the 
CORP server's SYS: volume) shows how to log activity to a volume other 
than the Btrieve data file's volume. This entry directs Btrieve to log 
activity in the file \DATA\B.BTR on the CORP server's SYS: volume into 
the log file \DATA\B.LOG on the VOL1: volume of the CORP server. 


\data\b.btr=\\corp\vol1:\data\b.log 


Be sure to make a backup copy of your Btrieve data files before logging 
begins. When logging is activated for a given file, Btrieve records (in the 
corresponding log file) all the operations that change that file. Btrieve 
continues appending subsequent operations to the end of this log file until the 
log file is deleted. Consequently, it is important to perform periodic 
maintenance to reduce the size of the log files. 


IMPORTANT: Every time you back up your Btrieve data files, delete the 
associated log files before executing any further operations that could change the 
files. Synchronization of the backup data files and the associated log files is critical 
to recovering operations successfully. 
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Running the Roll Forward Utility in a DOS Environment 


To run the Roll Forward utility in a DOS environment, enter the BROLLFWD 
command using the following format: 


BROLLFWD <btrvFile | @listFile | /A> [/D:nn] [/T:nn] [/ 
K:nn] [/H] [/V] [/L] [/0:ownerName] 


The following list describes the BROLLFWD command syntax: 





btrvFile 


@listFile 


IA 


/D: 


IT: 


IK: 


/H 


N 


IL 


/0: 





Specifies the name of a single Btrieve file to be recovered. 


Specifies the name of a text file that contains a list of Btrieve filenames separated 
by one or more spaces. Use a list file to recover multiple files. 


Specifies that you want to recover all the Btrieve files in the BLOG.GFG file. 


Specifies the data buffer size (in kilobytes) that the Roll Forward utility allocates for 
Btrieve log operations. /D: is optional. The default size is 8 KB, the minimum is 1 KB, 
and the maximum is 64 KB. You can specify the length in increments of 1 KB. 


Specifies the length of the data (in bytes) that will be printed in the list file for each 
operation that is rolled forward. /T: is optional. Valid data lengths range from 1 
through the value of the data buffer size specified with the /D: option. The default 
value is 40 bytes. 


Specifies the length of the key (in bytes) that will be printed in the list file for each 
operation that is rolled forward. /K: is optional. Valid lengths for printing keys range 
from 1 through 255 bytes. The default value is 10 bytes. 


Specifies that the Btrieve operations in the list file will be printed in hexadecimal 
format. The default prints the data and key in decimal numbers. /H is optional. 


Specifies that for each logged file in the list file, the utility will add the time stamps 
of the Roll Forward operation and log file creation. For each logged operation, it 
adds the name of the user who performed the operation, the internetwork address 
of the source workstation, the time stamp indicating when the operation was 
performed, and the record length and key number used in the operation. /V is 
optional. 


Specifies that you want only to list the logged operations. The logged operations will 
not be executed. The operations will be listed to the standard output device. /L is 
optional. 


Specifies an owner name. If the backup copy of the Btrieve file you want to recover 


has a Btrieve owner name, you must provide this option. This protects the owned 
files from being changed inadvertently. 
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Typically, all owned files in an application have the same owner name. Therefore, 
the utility assumes that all Btrieve files listed in the file list have the same owner 
name. 


However, some Btrieve files in a file list may have different owners. If a Btrieve file 
has an owner name, that file has only one owner name. In that case, the utility 
prompts you to enter the owner name. Similarly, if you do not specify /O and the 
utility encounters a Btrieve file that requires an owner name, BROLLFWD prompts 
you for that owner name. 


ownerName Specifies the owner name of the Btrieve files to be accessed. When you use /O, you 
must specify an owner name. 


Running the Roll Forward Utility in an OS/2 or Windows Environment 


The following list shows a few ways you can run the Roll Forward utility: 








From This Position Do This 

OS/2 command line Type PBROLL 

Presentation Manager Double click on the Roll Forward icon 

Windows Double click on the Roll Forward icon, or choose Run... from the 


File pulldown menu and type WBROLL 


NOTE: The following documentation applies to both OS/2 and Windows operating 
environments, but the screen examples show Windows screens only. 


To use the Roll Forward utility in the OS/2 and Windows environments, you need 
to complete the following steps: 


1. Set the Roll Forward utility's program options. 
2. Place in the utility's queue all the items you intend to roll forward. 


3. Start rolling forward the items in the queue. 


Following a brief description of the Roll Forward utility's pulldown menus, 
subsequent sections describe each of these steps in detail. 
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Using the Roll Forward Pulldown Menus 


After starting the Roll Forward utility, you can access two pulldown menus: 
Queue and Options. 


HINT: If you are not using a mouse, you can access the menus by pressing and 
holding the Alt key while typing the letter highlighted in the menu selection. For 
example, to select the Queue pulldown menu, hold down the Alt key and press Q. 
To move between fields in the dialog boxes, use the Tab key. 


Queue Menu 


When you select Queue from the main menu, a pulldown menu offers the 





following: 
Add... Generates a dialog box in which you can specify items to be placed in the queue. 
View... Generates a dialog box in which you can view the queued items. If no items are in 


the queue, this selection is disabled. 


Start Begins the process of rolling forward all items in the queue. Like the View... 
selection, this selection is disabled if no items are in the queue. 


Exit Exits the utility. In the Windows and OS/2 environments, you can also press F3 to 
exit. 


Options Menu 


When you select Options from the main menu, a pulldown menu offers the 





following: 
Options... Generates a dialog box that lets you set the data buffer length and the list options. 
About... Displays the version of the Roll Forward utility that you are running. 





Setting Options for the Roll Forward Utility 


You should set program options for the Roll Forward utility before using the 
utility to roll forward changes. These options control the following: 


+ Size of the data buffer used to retrieve records 
+ Multitasking operation 


+ Contents of the list file (BROLL.LST) 
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Table 6 describes each of these options in detail. Subsequent sections describe 
the two methods you can use to set the program options: 


+ By using the Options pulldown menu. 
+ By editing the initialization file. (The NOVDB.INI file for OS/2 cannot 
be edited.) 


Table 6 Roll Forward Program Options 





Program Option Description 





Data Length Specifies the number of kilobytes allocated for the data buffer that the 
utility uses to process the logged entries. This number should be at 
least as large as the largest record to be rolled forward. The default is 
4 KB. 


Exclusive Operation Runs in one of two ways, depending on your operating system: 


MS Windows MS Windows 3.x emulates multitasking and lets 
you run more than one application concurrently. If 
you select Exclusive Operation, the Roll Forward 
utility uses the CPU time exclusively. If you do not 
select this option, the utility shares CPU time with 
other applications. 


If you plan to run recorder-type programs or batch 
execution programs with Roll Forward, check this 
box to ensure correct operation. Selecting 
Exclusive operation also enhances performance 
slightly. 


OS/2 OS/2 provides true multitasking; the Roll Forward 
utility can always run concurrently with other 
applications. You can, however, vary the priority of 
the Roll Forward thread to accommodate other 
threads that are running. The following priorities are 
available: 


Idle—Runs only when no other tasks are waiting for 
the CPU 


Low—Lower priority than normal 
Normal—The default thread priority 


High—Higher priority than normal 
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Program Option 


Description 








List Files 


Specifies the listing options for the list file BROLL.LST. You can select 
one of the following: 


Verbose 


Data to list 


Key to list 


ASCII 


Hex 


For each logged file, this option adds the time 
stamps of the Roll Forward operation and log file 
creation to the list file. For each logged operation, it 
adds the name of the user who performed the 
operation, the internetwork address of the source 
workstation, the time stamp indicating when the 
operation was performed, and the user-defined 
lengths of data and key numbers used in the 
operation. 


Specifies the length of the data buffer that will be 
printed in the list file for each operation that is rolled 
forward. 


Specifies the length of the key buffer that will be 
printed in the list file for each operation that is rolled 
forward. 


Lists the Btrieve operation values in ASCII mode. 


Lists the Btrieve operation values in hexadecimal 
mode. 
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Setting Options from the Options Menu 
To set Roll Forward options using the Options pulldown menu, complete the 
following steps: 
1. Select Options from the Roll Forward main menu. 
2. Select Options... from the Options pulldown menu to display the 
following dialog box: 





a 


Data Length [KB] 


E Exclusive Operation 








List Files 
O Verbose 


0 Data to list (bytes) 
0 Key to list [bytes] 


$ ASCII © Hex 











3. Set the options using the guidelines provided in Table 6. 


4. After setting the options, select one of the following: 
+ Save—accepts and saves the changes you have made to the .INI file. 


+ OK—accepts the changes but does not save them to the .INI file. 


+ CANCEL—cancels the changes and returns to the previous screen. 
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Setting Options in the Initialization File 


You can also change the setting of the Roll Forward utility's program options 
by editing the initialization file NOVDB.INI (for Windows). These settings 
are specified under [wbroll] in NOVDB.INI. An example specification for 
[wbroll] follows: 


[wbro11] 
datalength=4 
exclusive=no 
outputmode=ASCII 
listverbose=yes 
datalist=32 


keylist=16 


Placing Items in the Queue 


The Roll Forward utility works on a queued-job basis. When you specify the 
Btrieve files that are to be rolled forward, the utility places them in the queue. 


This section discusses the Roll Forward utility's queue and explains how to do 
the following: 


+ Add items to the queue 
+ Delete items from the queue 
+ Change list options for a queued item 


+ View items in the queue 


Adding Items to the Queue 


The queue can hold a maximum of 32 items. Any of the following represents 
one item: 


+ An individual Btrieve file 
+ A text file listing several Btrieve files 


¢ All files from a specified volume 
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To add items to the queue, complete the following steps: 


1. Select Add... from the Queue pulldown menu. The Add... dialog box 
(similar to the following) appears: 


Btrieve Roll Forward 









O Entire Volume O List Only 
Filename: O List File 


a [Owner]: 


Current Directory 
u‘\blog 











Files Directories 


blog.cfg 
dental.dsc 
test.dat 
testlog 
test0.dat 
test0.log 
test] dat 
test] log 





















2. Select the Btrieve file or files to be rolled forward, as follows: 
+ To select the entire volume, click on the Entire Volume check box. 


¢ To select a particular file, scroll the Directories list box (the list box 
on the right) to find your directory or drive. Double click on the 
directory name and then choose the filename from the Files list box 
(the list box on the left). 


+ To enter a text file containing a list of files, enter the filename in the 
Filename text box. To select all available files with a certain 
extension, you can enter a wildcard character for the filename, 
followed by the extension. Then, press Enter. 


NOTE: To select the parent directory from the Directories list box, set "show 
dots=on" in your NET.CFG file. Refer to your NetWare documentation for 
more information on NET.CFG. 


3. Specify the list option for the queue item you are adding, as follows: 


¢ If you want only to list the Btrieve operations to be rolled forward 
(without actually rolling the logged operations forward), click on the 
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List Only and List File check boxes. The operations will be listed in 
the file BROLL.LST in the BLOG directory. 


¢ Ifyou want to list the operations in BROLL.LST and roll forward the 
operations, click on the List File check box. 


¢ If you do not want to list the operations that are rolled forward but 
you do want to roll the operations forward, do not click on either the 
List Only or List File checkbox. 


4. If the Btrieve file has an owner name, specify the owner name in the 
Owner text box. 


5. Click on the Add button to add the item to the queue. 
6. Repeat Steps 2 through 5 to add each additional item to the queue. 


7. To review the items you have placed in the queue, click on the Queue... 
button. 


The items selected appear on a screen similar to the following: 


Roll Forward Queue 





O List Only O List File 







k:Ablogttest.dat 

kblog\test0.dat 
kiblogitestl.dat 
kAblogltestl O.dat 
kiblogítestl1.dat 


















8. When you are finished, click on the OK button. 


NOTE: At any time, you can click on the CANCEL button to cancel your changes 
and return to the previous screen. 
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Deleting Items from the Queue 


If you need to delete an item from the queue, complete the following steps: 


f; 


Select View... from the Queue pulldown menu. 


2. Select the item you want to delete. 
3. 
4. Click on the OK button. 


Click on the Delete button to remove the item from the queue. 


NOTE: If you change your mind and want to cancel your deletion, click on the 
CANCEL button instead of OK. 


Changing List Options for a Queued Item 


You can use either of the following methods to change the list options (that is, 
your choices regarding the List Only and List File check boxes) for a given 
queue item: 


+ Select Add... from the Queue menu and then click on the Add button. 


Next, select the relevant item and choose the list option you prefer. 


+ Select View... from the Queue menu, select the relevant item, and choose 


the list option you prefer. 


Viewing Items in the Queue 


You can use either of the following methods to view items in the queue: 


+ From the Queue pulldown menu, select View... to display a dialog box 


that lists the queued items. (You can select this option only if the queue 
has one or more items in it.) 


+ While you are adding items to the queue, click on the Queue... button to 


list the files in the queue. 
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Rolling Forward Items in the Queue 


Once the queue contains all the items for which you want to roll forward 
changes, you are ready to start the roll forward process. Select Start from the 
Queue pulldown menu. 





NOTE: The Roll Forward utility allows a maximum of 250 concurrent transactions 
per Btrieve file during the roll forward process. 


After you select Start, the utility lists each Btrieve file being rolled forward and 
specifies the number of logged entries for each file. (The number of logged entries 
is shown to the left of the filename.) 


pet Btrieve Roll Forward 
Queue Options 
Entries Filename 





00000000 \blog\test0.dat 
00000010 \blog\test1.dat 
00000010 \blogitesti0.dat 
00000013 \blog\test11.dat 
00000010 \blog\testl2.dat 
00000010 \blogitesti3.dat 
00000010 \blog\testl 4.dat 
00000010 \blog\test3.dat 
00000010 \blog\test4.dat 
00000010 \blog\test5.dat 
00000010 \blog\test6.dat 
00000010 \blog\test?.dat 
00000010 \blogitesté.dat 
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Description Files 


A description file is an ASCII file containing information that the 
Maintenance utility commands CREATE, INDEX, and SINDEX need to 
perform their operations. 


Description files contain one or more elements. An element consists of a 
keyword, followed by an equal sign (=), followed by a value (with no space). 
Each element in the description file corresponds to a particular characteristic 
of a Btrieve file or key definition. 


The sections in this appendix discuss the following topics: 
+ “Rules for Description Files” on page 137 
+ “Description File Example” on page 139 


+ “Description File Elements” on page 142 


Rules for Description Files 


Use the following rules when creating a description file. 
+ Enter elements in lowercase, as in the following example: 
type=flo 


+ Separate elements from each other with a separator (blank space, tab, or 
carriage return/line feed), as in the following example: 


record=4000 


key=24 
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+ Specify the description file elements in the proper order. Table 7 presents 
the elements in the appropriate order. 


NOTE: The order of the elements required for the CREATE, INDEX, and SINDEX 
commands is the same. However, these commands do not all require the same 
elements. 


+ Address all element dependencies. For example, consider the following 
Null Key element: 


null=y 


If you specify this element in the description file, you must also include 
the Null Key Value element. 


+ Define as many keys as you specify with the Key Count element. The 
following example specifies 12 keys for the file: 


key=12 


In this case, you must define 12 keys in the description file, each 
consisting of one or more segments. 


+ Fora key with multiple segments, you must define the following elements 
for each key segment: 


+ Key Position 
+ Key Length 
+ Duplicate Key Values 
+ Modifiable Key Values 
+ Key Type 
+ Alternate Collating Sequence 
The Descending Sort Order element is optional for each segment. 


+ If any key in the file uses an alternate collating sequence, include either 
an alternate collating sequence filename or a country ID and code page 
ID. You can include this information as either the last element of the key 
segment or the last element in the description file. 


+ Ifa description file element is optional, you can omit it from the 
description file. 


+ Make sure the description file contains no text formatting characters. 
Some word processors embed formatting characters in a text file. 
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Description File Example 


The sample description file shown in Figure 10, Figure 11, and Figure 12 
creates a Btrieve file. This Btrieve file has a page size of 512 bytes and 2 keys. 
The fixed-length portion of the record is 98 bytes long. The file allows 
variable-length records but does not use blank truncation. 


The file uses data compression, allows for Variable-tail Allocation Tables 
(VATs), and has the free space threshold set to 20 percent. Btrieve preallocates 
100 pages, or 51,200 bytes, when it creates the file. The file has two keys: Key 
0 and Key 1. Key 0 is a segmented key with two segments. 


Figure 10 Sample Description File Using Alternate Collating Sequence Filename 


key=2 page=512 allocation=100 replace=n 
Tthreshold=20 huge=-y 


position=1 length=5 duplicates-y 
nodifiable=n type=string altermate=y 
mil="r value=20 seqment=y 


position=6 length=10 duplicates=y 
nodifiable=n type=string alternate=y 
mil="r value=20 seqment=n 


position=16 length=2 duplicates=n 
modifiable=y type=numeric descending=y 
alternate=n null=n seqnent=n 


name=pa8A/upper.alt 





record=96 variable=y truncate=n conpress-y 


File 
Specificaions 


Key g 
Segment 1 


Key O 
segment 2 


Key 1 








In Figure 10, an alternate collating sequence filename (UPPER.ALT) is 


specified for Key 0. 


If you specify y for the Alternate Collating Sequence element for a key, you 
must supply an alternate collating sequence filename or a country ID and code 


page ID. 
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Figure 11 Sample Description File Using Alternate Collating Sequence ID 


key=2 page=512 allocation=100 replace=n 


record=96 variable=y truncate=n conpress-y | File 
fthreshold=20 huge=-y 


Specifications 


position=1 length=5 duplicates=y Key 0 
noditiable=n type=string altermate-y Segment 1 
mil=r value=20 seqment=y j 
position=6 length=10 duplicates=y Key Ú 
nodifiable=n type=striny alternate-y Segment 2 
mull=y¥ value=20 seqment=n ` 
position=16 length=2 duplicates=n 

nodifiable=y type=numeric descending=-y Key 1 


altermate=n null=n seqnent=n 


countryid=-1 codepageid=-1 











In Figure 11, a country ID and code page ID are specified (countryid=-1 and 
codepageid=-1). If you specify the name=sequenceFile element (or the 
countryid=nnn and codepageid=nnn elements) at the end of the description 
file, Btrieve uses it as the default alternate collating sequence. 


That is, if you specify alternate=y for a given key but do not include a 
name=sequenceFile element (or the countryid=nnn and codepageid=nnn 
elements) for that key, Btrieve uses the name=sequenceFile element (or the 
countryid=nnn and codepageid=nnn elements) specified at the end of the 
description file. 
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Figure 12 Sample Description File Using Alternate Collating Sequence Filename on 
a File Segment 


record=96 variable=y truncate=n conpress=-y File 
key=2 page=512 allocation=100 replace=n Specilivialionts 
fthreshold=20 huge=-y H 


position=1 length=5 duplicates-y Key 0 
nodifiable=n type=string altermate-y i 


mull=y value=20 segment=y nane=path/lower.alt | segment 1 


position=6 length=10 duplicates-y e 
nodifiable=n type=string alternate=y Key 0 
mll=y value=20 seqnent=n name=path/lower.alt | 5egment 2 
position=16 length=10 duplicates=n =] 
modifiable=y type=string descending-y Koy 1 
alternate=y null=n segment=n 
Nane=patit/upper.alt 














In Figure 12, a different alternate collating sequence filename is specified for 
Key 0 and Key 1. If you want to use different alternate collating sequences for 
different keys, you must specify the name=sequenceFile element (or the 
countryid=nnn and codepageid=nnn elements) for each key that uses a 
different alternate collating sequence. 


Different segments of the same key cannot have different alternate collating 
sequences. 


You can specify only one alternate collating sequence per key, and you must 
provide an alternate collating sequence filename (or values for the 
countryid=nnn and codepageid=nnn elements) for each segment of the key. 


The filename for the name=sequenceFile element (or values for the 
countryid=nnn and codepageid=nnn elements) must be the same for each 
segment. In Figure 12, the filename specified for each segment in Key 0 is 
LOWER.ALT. The filename specified for Key 1 is UPPER.ALT. 
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Description File Elements 


Table 7 lists the description file elements in the order in which they must 
appear in the description file. For each element, Table 7 specifies the required 
format, the range of acceptable values, and the associated commands. An 
asterisk (*) after the element name indicates that the element is optional. 
Descriptions of the individual elements follow the table. 








Table 7 Summary of Description File Elements 
Element Format Range Command 
“Record Length” on page  record=nnnn 4-4,088 CREATE 
144 
“Variable-Length Records”  variable=<y|n> N/A CREATE 
on page 144 
“Reserved Duplicate dupkey=<nnn> 1-119 CREATE 
Pointer” on page 144 
“Blank Truncation” on page  truncate=<y|n> N/A CREATE 
145 
“Data Compression” on compress=<y|n> N/A CREATE 
page 145 
“Key Count” on page 145  — key=nnn 0-119 CREATE 
“Page Size” on page 146 page=nnnn 512-4,096 CREATE 
“Page Preallocation” on allocation=nnnnn 1-65,535 CREATE 
page 146 
“Replace Existing File” on  replace=<y|n> N/A CREATE 
page 147 
“Include Data” on page 147 data=<y|n> N/A CREATE 
“Free Space Threshold” on  fthreshold=<10|20/30> N/A CREATE 
page 147 
“Key Position” on page 149 position=nnnn 1-4,088 CREATE, INDEX, SINDEX 
“Key Length” on page 150  length=nnn key type limit CREATE, INDEX, SINDEX 
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Element Format Range Command 

“Duplicate Key Values” on duplicates=<y|n> N/A CREATE, INDEX, SINDEX 
page 150 

“Modifiable Key Values” on modifiable=<y|n> N/A CREATE, INDEX, SINDEX 
page 150 

“Key Type” on page 151 type=validBtrieveKeyType N/A CREATE, INDEX, SINDEX 
“Descending Sort Order” descending=<y|n> N/A CREATE, INDEX, SINDEX 
on page 151 

“Alternate Collating alternate=<y|n> N/A CREATE, INDEX, SINDEX 
Sequence” on page 152 

“Case-Insensitive Key” on  caseinsensitive=<y|n> N/A CREATE, INDEX, SINDEX 
page 152 

“Repeating Duplicates” on repeatdup=<y|n> N/A CREATE, SINDEX 

page 153 

“Manual Key” on page 154 manual=<y|n> N/A CREATE, INDEX, SINDEX 
“Null Key” on page 155 null=<y|n> N/A CREATE, INDEX, SINDEX 
“Null Key Value” on page — value=nn 1-byte hex CREATE, INDEX, SINDEX 
155 

“Segmented Key” on page segment=<y|n> N/A CREATE, INDEX, SINDEX 
156 

“Alternate Collating name=sequenceFile or valid path or CREATE, INDEX, SINDEX 


Sequence Filename/ID” on 
page 156 


countryid=nnn and 
codepageid=nnn 


values valid to 
operating system 
or -1 (default) 
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Record Length 
Format: record=nnnn 
Range: 4 through 4,088 bytes 
Command: CREATE 


The Record Length element defines the logical data record length in bytes. For 
fixed-length records, this value should correspond to the length of the data 
buffer parameter that performs operations on the file. For variable-length 
records, this value should correspond to the fixed-length portion of the record. 


The data record length must be at least 4 bytes and must be large enough to 
contain all the keys defined for the file. The record length (including its 
duplicate key overhead and usage count overhead) plus 6 bytes must not 
exceed the file's page size. 


Variable-Length Records 
Format: variable=<y|n> 
Range: Not applicable 
Command: CREATE 


The Variable-Length Records element specifies whether the file will contain 
variable-length records. If a record is variable length, the maximum fixed- 
length record is decreased by 4 bytes. Specify y if you want the file to allow 
variable-length records; otherwise, specify n. 


Reserved Duplicate Pointer 
Format: dupkey=nnn 
Range: | through 119 
Command: CREATE 


The Reserved Duplicate Pointer element is optional. It specifies the number of 
duplicate key pointers to preallocate for the file when it is created. Each 
reserved duplicate pointer adds 8 bytes of extra storage space to the fixed 
record length. These reserved pointers can be used when keys that allow 
duplicates are added after the file is created and if you do not specify y for the 
Repeating Duplicates element. 
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Blank Truncation 
Format: truncate=<y|n> 
Range: Not applicable 
Command: CREATE 


The Blank Truncation element is optional. It specifies whether Btrieve 
performs blank truncation on variable-length records. The truncate element 
has an effect only if you specify y for the Variable-Length Records element. 


Specify y if you want Btrieve to use blank truncation. Otherwise, either 
specify n or omit this element from your description file. 


Data Compression 
Format: compress=<y|n> 
Range: Not applicable 
Command: CREATE 


The Data Compression element is optional. It specifies whether Btrieve 
performs data compression on records that are inserted into the file. 


Specify y if you want Btrieve to perform data compression. Otherwise, either 
specify n or omit this element from your description file. 


Key Count 
Format: key=nnn 
Range: 0 through 118 (see “Key Segment Count Values” on page 146) 
Command: CREATE 


The Key Count element specifies the number of keys to be defined in the file. 
If you specify a value of 0 for this element, Btrieve creates a data-only file. If 
you specify a value greater than 0, Btrieve creates either a standard file or a 
key-only file, depending on the value you specify for the Include Data 
element. 


The file's page size limits the amount of key segments a file can have. Table 8 
shows the maximum key count values for each possible page size. This value 
represents the number of key segments, not the number of keys. 
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Table 8 


Page Size (in bytes) 


There may actually be more segment definitions than the key count. For 
example, assume a file contains three keys: key O has 2 segments, key 1 has 4 
segments, and key 2 has 2 segments. In this example, the file has a page size 
of 512, the value specified for the Key Count element is 3, and the maximum 
number of key segments is 8. 


Key Segment Count Values 


Maximum Number of Key Segments 





512 

1,024 
1,536 
2,048-3,584 


4,096 


Page Size 


8 
23 
24 
54 


119 


Format: page=nnnn 
Range: 512 through 4,096 bytes 
Command: CREATE 


The Page Size element specifies the physical page size (in bytes) for the file. 
You can specify any multiple of 512, up to 4,096. 


HINT: For optimum performance, set the page size to 512, 1,024, 2,048, or 4,096 
bytes. 


Page Preallocation 


Format: allocation=nnnnn 
Range: | through 65,535 
Command: CREATE 


The Page Preallocation element is optional. It specifies the number of pages 
to preallocate to the file. If you do not want to preallocate any pages, either 
specify n or omit this element from your description file. 
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Replace Existing File 


Include Data 


Format: replace=<y|n> 
Range: Not applicable 
Command: CREATE 


The Replace Existing File element is optional. If you do not want to create a 
new, empty file over an existing Btrieve file of the same name, specify n. If 

you want to replace an existing Btrieve file with a new, empty file of the same 
name, either specify y or omit this element from your description file. 


Format: data=<y|n> 
Range: Not applicable 
Command: CREATE 


The Include Data element is optional. It specifies the file type that the utility 
creates. To create a key-only file, specify n. To create a standard file, either 
specify y or omit the element from the description file. To create a data-only 
file, specify y and set the Key Count element to 0. 


Free Space Threshold 


Format: fthreshold=<10|20|30> 
Range: Not applicable 
Command: CREATE 


Btrieve stores the variable-length portions of records on their own pages 
(called variable pages), separate from the fixed-length portion of the record 
(which is stored on a data page). Btrieve maintains the Free Space List for 
variable pages. The Free Space List indicates which variable pages contain the 
same or more free space than that specified by the Free Space Threshold file 
specification. 


You can specify a value for the Free Space Threshold element when you create 
the file. This value is expressed as a percentage and tells Btrieve how much 
free space must remain on a variable page in order for that page to appear on 
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the Free Space List. When Btrieve adds new variable-length records to the file, 
it uses pages in the Free Space List before using new variable pages. 


After each Insert, Update, or Delete operation, Btrieve rechecks the remaining 
space on the affected variable page to see if it is still above the threshold to 
qualify for the Free Space List. 


The free space threshold feature provides a means of reducing the 
fragmentation of variable-length records across several pages. A higher free 
space threshold reduces fragmentation at the cost of requiring more disk space 
for the file. 


You can specify any two-digit number for this element, and the utility rounds 
it to 10, 20, or 30. 


Btrieve uses a default free space threshold of 5 percent if either of the 
following is true: 


+ You specify a value less than 10. 


+ You do not specify a value here but have specified y for the Variable- 
Length Records element. 


NOTE: If the Btrieve file does not allow variable-length records, do not include this 
element in the description file. 


Variable-Tail Allocation Tables (VATs) 
Format: huge=<y|n> 
Range: Not applicable 
Command: CREATE 


The Variable-tail Allocation Tables (VATs) element is optional. Btrieve v6.1 
allows an application to create Btrieve files that contain structures called 
Variable-tail Allocation Tables (VATs), which are implemented as linked lists. 


To accelerate random access to portions of records, Btrieve uses VATs with 
each record. VATs are also helpful in files using data compression to limit the 
size of the compression buffer that Btrieve uses. If you want to create a file 
that uses VATs, specify y. Otherwise, either specify n or omit this element 
from your description file. 


NOTE: For more information about VATs, refer to the Btrieve Programmer's 
Manual. 


148 Birieve Installation and Operation 


Balanced Index 


Key Position 


Format: balance=<y|n> 
Range: Not applicable 
Commands: CREATE 


The Balanced Index element is optional. This feature allows you to use index 
balancing. With index balancing, Btrieve looks for available space in sibling 
index pages each time an index page becomes full and then rotates values from 
the full page into the pages with space available. 


Index balancing increases index page utilization, results in fewer pages, and 
produces an even distribution of keys among nodes on the same level, thus 
enhancing performance during Get operations. However, the use of this 
feature also means that Btrieve requires extra time to examine more index 
pages and may require more disk I/O during Insert, Update, and Delete 
operations. 


NOTE: You can specify index balancing on a file-by-file basis when the file is 
created. When you specify index balancing for a specific file, Btrieve will always 
balance that file's keys. You can also turn index balancing on and off for files that 
are not flagged as balanced by specifying Yes to the Perform Index Balancing 
configuration option in the Setup utility. 


To use index balancing, specify y. Otherwise, either specify n or omit this element 
from the description file. 


Format: position=nnnn 
Range: | through value specified for Record Length element (up to 4,088) 
Commands: CREATE, INDEX, SINDEX 


The Key Position element indicates the position of the key segment in the 
record. The key position value must be at least 1 and cannot exceed the value 
you specified for the Record Length element. 
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Key Length 
Format: length=nnn 
Range: | through limit determined by key type 
Commands: CREATE, INDEX, SINDEX 


The Key Length element defines the length of the key or key segment field. 
The value you specify here cannot exceed the limit dictated by the key type, 
which the Key Type element specifies. The key length must be an even 
number if the key is a binary key type. The total of the key's length and starting 
position cannot exceed the file's defined record length. 


Duplicate Key Values 
Format: duplicates=<y|n> 
Range: Not applicable 
Commands: CREATE, INDEX, SINDEX 


The Duplicate Key Values element specifies whether more than one record in 
the file can contain the same value for this key field. Specify y if you want to 
allow duplicate values for the key field; otherwise, specify n. 


NOTE: If you define duplicate key values for one segment of a segmented key, you 
must define duplicate key values for every segment of that key. For a segmented 
key that does not allow duplicates, the segments may contain duplicates between 
multiple records only if the key value is unique for each record. 


Modifiable Key Values 
Format: modifiable=<y|n> 
Range: Not applicable 


Commands: CREATE, INDEX, SINDEX 


The Modifiable Key Values element specifies whether the key value can be 
modified during an Update operation. Specify y if you want the values for this 
key to be modifiable; otherwise, specify n. 


NOTE: If you define modifiable key values for one segment of a segmented key, 
you must define modifiable key values for every segment of that key because the 
key, as a whole, is modifiable. 
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Key Type 
Format: type=validBtrieveKeyType 
Range: Not applicable 
Commands: CREATE, INDEX, SINDEX 


The Key Type element specifies the Btrieve data type for the key. This element 
determines how Btrieve will sort the bytes specified for this key segment. 
Btrieve does not perform any validation on the data inserted. You can specify 
the entire word (as in float) or just the first three letters of the word (as in flo 
for float). The Btrieve key types are as follows: 





autoinc integer string 

bfloat logical time 

date Istring unsigned binary 
decimal money zstring 

float numeric sign trailing separate 


NOTE: STS (sign trailing separate) is a COBOL data type. It is basically a numeric 
data type, represented as an ASCII string. STS is right justified and padded with 
leading ASCII zeros, and it has the sign byte at the end. 

Descending Sort Order 
Format: descending=<y|n> 
Range: Not applicable 
Commands: CREATE, INDEX, SINDEX 


The Descending Sort Order element is optional. It specifies whether Btrieve 
will collate the index or index segment in descending order. 


Specify y if you want Btrieve to collate the key values in descending order. If 
you want Btrieve to collate the index in ascending order, either specify n or 
omit this element from the description file. 
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Alternate Collating Sequence 
Format: alternate=<y|n> 
Range: Not applicable 
Commands: CREATE, INDEX, SINDEX 


The Alternate Collating Sequence element is optional. This element allows 
you to specify one or more alternate collating sequences for a given file. An 
alternate collating sequence specifies whether Btrieve will sort a key by a 
collating sequence other than the standard ASCII sequence. 


You can specify a different alternate collating sequence for each key. 
However, each segment of the key can have only one alternate collating 
sequence. Alternate collating sequences are valid only for string, Istring, and 
zstring key types. If you want the key to take advantage of an alternate 
collating sequence, specify y. Otherwise, either specify n or omit this element 
from the description file. 


When using a description file to create an additional index for an existing 
Btrieve file, if you want the index to use an alternate collating sequence file 
other than the first one in the Btrieve file, specify alternate=y and 
caseinsensitive=y. 


If you specify alternate=y and caseinsensitive=n and use an alternate collating 
sequence file other than the first one in the Btrieve file, the index will not be 
created. 


Case-Insensitive Key 
Format: caseinsensitive=<y|n> 
Range: Not applicable 
Commands: CREATE, INDEX, SINDEX 


The Case-Insensitive Key element is optional. It specifies that the key (or key 
segment) you are defining is case insensitive. You can specify this key element 
only for keys that are of type string, zstring, or Istring. 


By default, Btrieve is case sensitive when sorting key strings; that is, 1t sorts 
string key values based on whether the letters are uppercase or lowercase. 
Btrieve sorts the values by placing the uppercase value first, followed by the 
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lowercase value. For example, key values starting with A would appear before 
those starting with a in the index. 


Case sensitivity, however, does not apply if Btrieve sorts a key according to 
the collating sequence specified with the Alternate Collating Sequence 
element. 


To specify that Btrieve ignore case when sorting the key value, specify y for 
this element. Otherwise, either specify n or omit this element from the 
description file. 


Repeating Duplicates 
Format: repeatdup=<y|n> 
Range: Not applicable 
Commands: CREATE, INDEX, SINDEX 


Btrieve uses two methods for storing duplicatable keys internally. The keys 
are stored as either linked-duplicatable keys or repeating-duplicatable keys. 


+ Linked-duplicatable key—In a Btrieve v6.1 file, Btrieve stores 
duplicatable keys as linked-duplicatable keys by default on a Create 
operation. (On a Create Index operation, Btrieve uses linked-duplicatable 
keys if they are available; otherwise, it uses repeating-duplicatable keys, 
as explained in the following section.) Using this method, Btrieve stores 
the key extracted from the first record of a duplicatable key on an index 
page. 

Other records with keys containing duplicate values are stored in the form 
of a linked list, with pointers at the end of each record in a data page 
pointing to the next and the previous records that have the same duplicate 
key values. 


+ Repeating-duplicatable key—If no room is available to create a linked- 
duplicatable key (that is, if no duplicate pointers were reserved at file 
creation, or if no index has been dropped to free existing pointers), 
Btrieve stores duplicatable keys as repeating-duplicatable keys. Using 
this method, Btrieve stores every key value of a repeating-duplicatable 
key both in a data page and in an index page. 


NOTE: Key-only files always use repeating-duplicatable keys because the key- 
only files use only the index pages and not the data pages. 
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Manual Key 


Specify y to create repeating-duplicatable keys. Otherwise, either specify n or 
omit this element from the description file. 


NOTE: For a segmented key, all segments must have the same repeatdup=y/n 
specification. For a nonsegmented key, if you specify repeatdup=y, you must also 
specify duplicate=y. 


Format: manual=<y|n> 
Range: Not applicable 
Commands: CREATE, INDEX, SINDEX 


The Manual Key element is optional. It specifies that the key or key segment 
you are defining is manual. A manual key is a modified form of the null key 
and can be used to exclude particular records from the index. 


Manual keys have all the attributes of a null key with one exception: in a 
manual key, if every byte of one segment of the key contains the null value, 
Btrieve excludes the key from the index even if other segments do not contain 
this null value. 


If you define one segment of a key as a manual key, you must define a null 
value for that segment, and you must define all other segments of that key as 
manual. However, Btrieve allows you to define different null values for 
different segments in a segmented key. 


To create a manual key or key segment, specify y; otherwise, specify n or omit 
this element from your description file. 


NOTE: The Birieve Programmer's Manual refers to manual keys as any-segment 
null keys. 
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Null Key 


Null Key Value 


Format: null=<y|n> 
Range: Not applicable 
Commands: CREATE, INDEX, SINDEX 


The Null Key element specifies whether the key you are defining has a null 
value. You can include the Null Key element in a description file for the 
INDEX command. However, to maintain consistent formats for the CREATE, 
INDEX, and SINDEX description files, INDEX disregards any null value you 
specify. 


If you define a null value for one segment of a segmented key, you must define 
a null value for every segment of that key. However, Btrieve allows you to 
define different null values for different segments in a segmented key. 


Specify y if you want to define a null value for this key. Otherwise, specify n. 


NOTE: The Btrieve Programmer's Manual refers to null keys as all-segment null 
keys. 


Format: value=nn 
Range: Any 1-byte hexadecimal value 
Commands: CREATE, INDEX, SINDEX 


The Null Key Value element specifies the null character value (in 
hexadecimal) for the key. Typical null values are 20 hexadecimal (blank) and 
0 hexadecimal (binary zero). Include this element only if you defined the key 
as allowing null values. If you specify n for both the Null Key element and the 
Manual Key element, the Null Key Value element is not required in the 
description file. 
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Segmented Key 
Format: segment=<y|n> 
Range: Not applicable 
Commands: CREATE, INDEX, SINDEX 


The Segmented Key element specifies whether the key you are defining has 
any more segments. Specify y if the key has another segment. Specify n if you 
are defining either a nonsegmented key or the last segment of a segmented 
key. 


Alternate Collating Sequence Filename/ID 
Format: name=sequenceFile or countryid=nnn codepageid=nnn 


Range: Any valid, fully qualified pathname; or a valid country ID and code 
page ID; or -1 (the default) 


Commands: CREATE, INDEX, SINDEX 


The Alternate Collating Sequence Filename/ID element specifies the 
pathname of the file that contains an alternate collating sequence for the file 
you are creating. You can include up to 256 bytes of directory levels in the 
pathname (plus the filename). 


If you specified n for the Alternate Collating Sequence element for every key, 
do not include this element in your description file. If you specified y for the 
Alternate Collating Sequence element for a key, you must supply either an 
alternate collating sequence filename or a country ID and a code page ID. 


If you want all the keys in the file to use the same alternate collating sequence 
filename, you can either specify this element as the last element in the 
description file or specify the alternate collating sequence name for each key. 


If you want to use different alternate collating sequences, you must specify 
this element for each key that uses an alternate collating sequence. 


You can specify only one alternate collating sequence per key, and each 
segment of the key should have an alternate= and name= pair. 


To use an alternate collating sequence ID, you must specify countryid=nnn 
and codepageid=nmnn. Use a valid country ID and code page ID. If you want to 
use the current locale, specify countryid=-1 and codepageid=-1. 
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The first 265 bytes of an alternating collating sequence file contain the 
definition of a collating sequence other than the standard ASCII sequence. If 
you want to create an alternate collating sequence file, generate a file in the 
format that Table 9 specifies. 








Table 9 Alternate Collating Sequence File Format 
Offset Length Description 
0 1 Signature byte. This byte should always contain the value ACh. 
1 8 An 8-byte name that uniquely identifies the alternate collating sequence to 
Btrieve. 
9 256 A 256-byte table containing the sort value for every character. Store the 


value for each sort character at the offset corresponding to the character's 
representation in the ASCII collating sequence. For example, to sort the 

character A as something other than 41h, store the new sort value at offset 
41h in the table. 





For example, assume you want to insert a character with a 5Dh between the 
letters U (55h) and V (56h) in your sequence. In this case, byte 5Dh in the 
sequence should contain the value 56h, and bytes 56h through 5Ch in the 
sequence should contain the values 57h through 5Dh. 
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Status Codes and Messages 


This appendix describes the Btrieve status codes and messages. The codes are 
listed first and appear in numeric order. The messages follow the codes and 
are listed in alphabetic order. 


Btrieve Record Manager Status Codes 


The Btrieve Record Manager returns a status code after each operation that an 
application performs. If the operation is successful, Btrieve returns Status 
Code 0. If the operation is not successful, Btrieve returns one of the nonzero 
status codes described in this section. 


01: The operation parameter is invalid. 


Explanation: The operation parameter specified in the call is invalid. 


02: Btrieve encountered an I/O error. 


Explanation: Btrieve encountered an error while reading from or writing to the disk. One of 
the following has occurred: 


+ The file is damaged and must be recreated. 


+ There isa large pre-image file inside a transaction, and there is not enough 
space for a write to the pre-image file. 


NOTE: Pre-image files are used only for files created by Btrieve versions earlier 
than v6.x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x 
Format configuration option set to Yes. 


¢ For Btrieve v5.x files, there is one pre-image file for multiple data files. 
For example, if you name the data files CUSTOMER.ONE and 
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CUSTOMER.TWO, both files will have pre-image files named 
CUSTOMER.PRE. 


¢ There is not enough space to append a new page to the data file. 


+ Client-based Btrieve attempted to write to a Btrieve file flagged shareable 
while server-based Btrieve had the file open. 


03: The file is not open. 


Explanation: The operation cannot be executed because the file is not open. The application 
must perform a successful Open operation before Btrieve can process any 
other operations. 


This status code may also be returned if the application passed an invalid 
position block for the file, or if the application passed a position block with a 
different client ID than the client ID used to open the file. 


04: Btrieve cannot find the key value. 


Explanation: Btrieve cannot find the specified key value in the index path. 


05: The record has a key field containing a duplicate key value. 


Explanation: Btrieve cannot add or update a record for the designated index because the 
record has a key field that contains a duplicate key value, and the index does 
not allow duplicate values. 


06: The key number parameter is invalid. 


Explanation: The value stored in the key number parameter is not valid for the file being 
accessed. The key number must correspond to one of the keys defined for the 
file. Valid key numbers are 0 through 118. 


07: The key number has changed. 


Explanation: The key number parameter changed before a Get Next, Get Next Extended, 
Get Previous, Get Previous Extended, Update, or Delete operation. The 
operation requires the same key number parameter as the previous operation 
because Btrieve uses positioning information relative to the previous key 
number. 


If you need to change key numbers between consecutive Get Next, Get Next 
Extended, Get Previous, Get Previous Extended, Update, or Delete 
operations, use a Get Position operation followed by a Get Direct/Record 
operation to reestablish positioning for the new index path. 
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08: The current positioning is invalid. 


Explanation: The current position must be established to update or delete a record. Perform 
a Get or Step operation to establish the current position. 


This status code may also be returned if the application passed an invalid 
position block for the file. 


09: The operation encountered an end-of-file condition. 
Explanation: This status code indicates one of the following conditions has occurred: 


+ The operation encountered an end-of-file boundary or tried to read past a 
file boundary (end-of-file or start-of-file). 


+ Ina Get Next Extended, Get Previous Extended, Step Next Extended, or 
Step Previous Extended operation, the number of records satisfying the 
filtering condition is less than the number of specified records to be 
returned, and the reject count has not been reached. 


+ When reading a file in ascending order according to an index path, 
Btrieve has already returned the last record in that index path. When 
reading a file in descending order according to an index path, Btrieve has 
already returned the first record in the index path. 


+ When using the Get By Percentage operation, either the value supplied 
for the percentage is too high—that is, it exceeds 10,000 decimal 
(0x2710)—or the file contains no records. 


10: The key field is not modifiable. 


Explanation: During an Update operation, an attempt was made to modify a key field that 
is defined as nonmodifiable. 


11: The specified filename is invalid. 
Explanation: This status code indicates one of the following conditions is true: 


¢ The filename specified does not conform to file naming conventions. 
Make sure the filename is valid for the environment. 


+ An attempt was made to open a file that has .^^^ as its extension. This 
extension is reserved for Btrieve to use during a continuous operation. 


+ The data buffer for a Begin or End continuous operation is not set up 
correctly. 
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12: Btrieve cannot find the specified file. 


Explanation: 


Check the key buffer parameter to make sure the pathname is terminated with 
a blank or a binary zero. Also, check to be sure the file exists. 


14: Btrieve cannot create or open the pre-image file. 


Explanation: 


There are four possible causes for this status code: 


NOTE: Pre-image files are used only for files created by Btrieve versions earlier 
than v6.x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x Format 
configuration option set to Yes. 


+ Btrieve cannot create a new pre-image file because the disk directory is 


full. Btrieve must be able to create a pre-image file. 


Btrieve cannot open the pre-image file to restore file integrity. If the pre- 
image file is erased or damaged, Btrieve cannot restore the file's integrity. 
In this case, either use the RECOVER command in the Btrieve 
Maintenance utility to retrieve the damaged file's data records in a 
sequential file, or replace the file with its most recent backup. 


Client-based Btrieve cannot assign a handle to the pre-image file because 
Btrieve was not started by a user with access rights to the pre-image file. 


The file structure of a pre-image file created by Btrieve v6.x is different 
from the file structure of a pre-image file created by Btrieve v5.x. If you 
have an extraneous .PRE file in Btrieve v5.x format and you are using 
Btrieve v6.x, Status Code 14 is returned when you try to open the Btrieve 
file to which the .PRE file belongs. 


15: Btrieve encountered an I/O error during pre-imaging. 


Explanation: 


This status code indicates either the disk is full or the pre-image file is 
damaged. 


NOTE: Pre-image files are used only for files created by Btrieve versions earlier 
than v6.x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x Format 
configuration option set to Yes. 


When this status code occurs, proceed as follows: 


¢ If the disk is full, erase any unnecessary files or extend the file to gain 


additional disk space. 


¢ Ifthe pre-image file is damaged, the integrity of the Btrieve file cannot be 


ensured. Either use the RECOVER command in the Btrieve Maintenance 
utility to retrieve the damaged file's data records in a sequential file, or 
replace the file with its most recent backup. 
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16: Btrieve encountered an expansion error. 


Explanation: 


Btrieve encountered an error while writing the directory structure to disk prior 
to creating the expanded file partition. Either Btrieve cannot close the file, or 
a new page was added to the file and Btrieve cannot close and reopen the file 
to update the directory structure. Check for a disk hardware failure. 


17: Btrieve encountered a close error. 


Explanation: 


18: The disk is full. 


Explanation: 


Btrieve encountered an error while writing the directory structure to disk prior 
to closing the file. Either Btrieve cannot close the file, or a new page was 
added to the file and Btrieve cannot close and reopen the file to update the 
directory structure. Check for a disk hardware failure. 


This status code may also be returned if the application passed an invalid 
position block for the file. 


This status code can be returned in the following situations: 


¢ The disk is full, and the file cannot be expanded to accommodate 


additional records. Either erase any unnecessary files or extend the file to 
gain additional disk space. 


The pre-image file is out of disk space. If you are working with files 
created by Btrieve versions earlier than v6.x and you are in a transaction, 
the pre-image file size increases for the duration of the transaction. If you 
receive this status, either reduce the number of operations in the 
transaction or obtain more disk space. 


The NetWare owner name for the file is no longer valid, and your 
application tried to insert or update records in the file, thus causing the file 
to expand. In this case, this status code is returned when Btrieve needs to 
add a page to the file, regardless of how much disk space is available. To 
check for an owner name, use the NetWare utility NDIR. To add an owner 
name, use the NetWare utility Filer. 


You can limit the amount of disk space available to each user in NetWare. 
This status code indicates an attempt was made to expand a Btrieve file 
beyond the amount of disk space allocated to the file's owner in NetWare. 
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19: The application encountered an unrecoverable error. 


Explanation: To ensure file integrity, either use the RECOVER command in the Btrieve 
Maintenance utility to retrieve the damaged file's data records in a sequential 
file, or replace the Btrieve file with its most recent backup. 


20: The Record Manager or Requester is inactive. 


Explanation: You must load Btrieve and, if applicable, the Btrieve Requester before 
generating any requests. 


21: The key buffer parameter is too short. 


Explanation: The key buffer parameter is not long enough to accommodate the key field for 
the index path requested. Verify that the length of the key buffer equals the 
defined length of the key specified in the key number parameter. Only 
language interfaces that track the buffer length can return this status code. 


22: The data buffer parameter is too short. 


Explanation: The data buffer parameter is not large enough to accommodate the length of 
the data record defined when the file was created. Verify that the length of the 
data buffer is at least as long as the file's defined record length. 


+ For Get or Step operations, Btrieve returns as much data as it can and a 
Status Code 22, indicating that it cannot return the entire record. 


+ Foran Insert operation, Btrieve does not insert the record if the data buffer 
is shorter than the fixed-length portion of the record. 


+ 


For an Update operation, if the data buffer is too short to contain the 
fixed-length portion of a record, Btrieve does not update the record. 


¢ For the Create, Stat, and Create Supplemental Index operations, the data 
buffer is not long enough to contain all the file specifications, the key 
specifications, and (if specified) the alternate collating sequence 
definition. 


+ For the Get By Percentage or Find Percentage operation, the data buffer 
length is less than 4 bytes. 


23: The position block parameter is not 128 bytes long. 


Explanation: Only language interfaces that track the position block length can detect and 
return this status code. 
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24: The page size or data buffer size is invalid. 
Explanation: Two possible reasons for receiving this status code are as follows: 


+ The page size is invalid. The page size must be a multiple of 512 bytes 
and cannot exceed 4,096 bytes. 


+ During a Create operation, the page size is the first file specification 
Btrieve checks. A Status Code 24 at this point may indicate an invalid 
data buffer parameter. 


In versions prior to Btrieve v6.1, this status code can be returned from the 
Open operation. In this case, Btrieve cannot open the file because the file's 
page size exceeds the Largest Page Size configuration option. To successfully 
open the file, you must increase the value of the Largest Page Size 
configuration option and then reload Btrieve. Btrieve v6.1 will not return 
Status Code 24 from the Open operation. 


25: Btrieve cannot create the specified file. 


Explanation: Possible causes are a full disk directory or a full disk. If the application is 
creating a file over an existing file, Btrieve returns this status code when the 
existing file is open or when the operating system prevents the operation for 
some other reason (for example, because the file is flagged transactional). 


26: The number of keys specified is invalid. 


Explanation: The number of keys specified for the page size is invalid. The number of key 
segments must be within the following limits: 








Page Size Max. Number Key Segments 
512 8 

1,024 23 

1,536 24 

2,048 54 

2,560 54 

3,072 54 

3,584 54 

4,096 119 
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27: The key position is invalid. 


Explanation: The key field position specified is less than 1 or exceeds the defined record 
length for the file. Either the key position is greater than the record length or 
the key position plus the key length exceeds the record length. 


28: The record length is invalid. 


Explanation: The record length specified (plus overhead for duplicates, record usage count, 
variable record pointers, record length, and blank truncation information) 
must be less than or equal to the page size minus 8 bytes, and greater than or 
equal to 4 bytes. 


29: The key length is invalid. 


Explanation: The key length specified must be greater than 0 but cannot exceed 255 bytes. 
The length of a binary key must be an even number. Btrieve requires that each 
key page in the file be large enough to hold at least eight keys. 


If the page size is too small to accommodate eight occurrences of the specified 
key length (plus overhead), either increase the file's page size or decrease the 
key length. 


30: The file specified is not a Btrieve file. 


Explanation: Either Btrieve did not create the file, or a version of Btrieve earlier than v3.x 
created it. 


This status code can also indicate that the first page of the file is damaged. Use 
a backup copy of your data file. 


31: The file is already extended. 


Explanation: The application tried to specify a file that has already been extended. A file 
can be extended only once. Files on a NetWare v3.x server using the Btrieve 
NLM cannot be extended. 


32: The file cannot be extended. 


Explanation: The application tried to specify a file that cannot be extended. Possible causes 
for receiving this status code are that the directory is full, the disk is full, or 
the disk is write protected. 
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34: The specified extension name is invalid. 


Explanation: The application specified an invalid filename for the extended partition. 
Check the validity of the filename. 


35: Btrieve encountered a directory error. 


Explanation: Either a Get Directory operation specified a drive that does not exist, or a Set 
Directory operation specified an invalid pathname. Check the validity of both 
the drive and the pathname. 


36: Btrieve encountered a transaction error. 


Explanation: Btrieve tried to perform a Begin Transaction operation without configuring 
Btrieve to allow transactions. Run the Setup utility and specify a higher value 
for the Number of Transactions configuration option. Next, stop and then 
restart Btrieve using BSTOP and BSTART so that your changes will take 
effect. 


37: Another transaction is active. 


Explanation: The application issued a Begin Transaction operation while another 
transaction was active by the same client (it can be an NLM or application). 
Btrieve does not accommodate nesting transactions. 


38: Btrieve encountered a transaction control file I/O error. 


Explanation: Btrieve encountered an error when it tried to write to the transaction control 
file. Possible causes for receiving this status code are that the disk is full, the 
disk is write protected, the transaction control file (BTRIEVE.TRN) that is 
created when you load Btrieve has been deleted or the transaction control file 
is flagged read only. 


39: A Begin Transaction operation must precede an End/Abort Transaction operation. 


Explanation: The application issued an End or Abort Transaction operation without a 
corresponding Begin Transaction operation. Make sure that each End or Abort 
Transaction operation in your program has a corresponding Begin Transaction 
operation. 
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40: The file access request exceeds the maximum number of files allowed. 


Explanation: 


The application tried to access more than the maximum number of files 
allowed within a transaction. The maximum number of different files that can 
be accessed during a logical transaction is set when Btrieve is configured. 


NOTE: This status code applies only to Btrieve versions earlier than v6.x. 


41: Btrieve does not allow the attempted operation. 


Explanation: 


This status code is returned for one of the following reasons: 


¢ The application tried to perform an operation that is not allowed at this 
time. Btrieve does not allow some operations under certain operating 
conditions. For example, Btrieve returns this status code if the application 
attempts to perform a Step operation on a key-only file or a Get operation 
on a data-only file. 


+ The key number parameter of a continuous operation call is not 0, 1, or 2. 


Also, Btrieve prohibits certain operations during transactions because they 
have too great an effect on the file or on Btrieve's performance. These 
operations include Set Owner, Clear Owner, Extend, Create Supplemental 
Index, and Drop Supplemental Index. 


42: A file previously opened in Accelerated mode was not closed. 


Explanation: 


Either the application tried to open a Btrieve v5.x file that was previously 
accessed in Accelerated mode by Btrieve v5.x and never successfully closed, 
or the application tried to open a file for which Btrieve v6.x encountered an 
unrecoverable error during a Set or Clear Owner operation. The file's integrity 
cannot be ensured. Either use the RECOVER command in the Btrieve 
Maintenance utility to build a new file or restore the file using the latest 
backup. 


43: The specified record address is invalid. 


Explanation: 


This status code is returned for one of the following reasons: 


¢ The record address specified for a Get Direct/Record operation is invalid. 
The address is outside the file's boundaries, it is not on a record boundary 
within a data page or on a data page, or the record at the specified address 
has been deleted. For a Get Direct/Record operation, specify the 4-byte 
address obtained by a Get Position operation. 
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+ When using Btrieve with NetWare and the files are Btrieve v5.x files, this 
error may indicate a file access conflict. For example, workstation 1 has 
a file locked in an exclusive transaction. Workstation 2 is reading records 
from the same file and tries to update a record that the transaction either 
inserted or updated. If workstation 2 reads the record and then 
workstation | aborts the transaction, workstation 2 receives this status 
code when issuing the Update operation. 


+ 


For a Find Percentage operation that is seeking a percentage based on a 
record's physical location within the file, the specified record address is 
invalid. 


+ The file may be corrupt, and you must rebuild it. 


44: The specified key path is invalid. 


Explanation: The application tried to use the Get Direct/Record operation to establish an 
index path for a key whose value is null in the corresponding record. Btrieve 
cannot establish positioning based on a null key value. 


45: The specified key flags are invalid. 


Explanation: The key flags specification on a Create operation is inconsistent. If a key has 
multiple segments, the duplicate, modifiable, and null attributes should be the 
same for each segment in the key. Also, you cannot use the Null or Manual 
key attributes in a key-only file. 


This status code is also returned if an attempt is made to specify a different 
alternate collating sequence for two or more segments of a segmented key. 


46: Access to the requested file is denied. 
Explanation: This status code is returned for one of the following reasons: 


+ The application opened a file in read-only mode and tried to perform an 
Insert, Update, or Delete on that file. 


+ An attempt was made to perform an Insert, Update, or Delete on a file that 
is flagged read-only to NetWare. 


+ The owner name required for updates was not specified correctly when 
the file was opened. 
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47: The number of files opened exceeds the maximum allowed. 


Explanation: 


The number of files opened in Accelerated mode exceeded the number of 
buffers available in Btrieve's cache. When a file is opened in Accelerated 
mode, Btrieve reserves one of its cache buffers for the file. Btrieve always 
reserves five empty buffers for index manipulation. In client-based Btrieve, 
you should reconfigure Btrieve with a smaller /P configuration option to 
allocate more buffers and a larger /M option. In server-based Btrieve, you will 
not encounter this error code. 


48: The alternate collating sequence definition is invalid. 


Explanation: 


The first byte of an alternate collating sequence definition (the identification 
byte) does not contain the hexadecimal value AC. Make sure that the first byte 
contains the proper value. 


49: The extended key type is invalid. 


Explanation: 


You tried to create a file or a supplemental index with an invalid extended key 
type, or you tried to assign an alternate collating sequence to a binary key or 
key segment. You can assign an alternate collating sequence only to a string, 
Istring, or zstring key type. 


This status code is also returned if you define a supplemental index requiring 
an alternate collating sequence, but no alternate collating sequence definition 
exists (either in the file or in the key definition passed in the data buffer). 


Another possibility is that you defined an alternate collating sequence with 
case insensitivity. These two definitions are incompatible. Only Btrieve v6.0 
interprets this condition as an error. 


A final possibility is that you are attempting to create a Btrieve file that 
contains multiple alternate collating sequences but your server has a version 
of Btrieve loaded that predates v6.1. 


50: The file owner is already set. 


Explanation: 


The application tried to perform a Set Owner operation on a file that already 
has an owner. Use the Clear Owner operation to remove the previous owner 
before specifying a new one. 
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51: The owner name is invalid. 
Explanation: The possible causes for this status code are as follows: 


+ If the application received this status code after a Set Owner operation, 
the owner names specified in the key buffer and data buffer do not match. 


+ If this status code occurred during an Open operation, the application 
attempted to open a file that has an owner name assigned to it. The 
application must specify the correct owner name in the data buffer. 


+ If an NLM received this status code when dealing with a file in 
continuous operation mode, then the client ID of the calling NLM differs 
from the client ID of the application that originally put the file into 
continuous operation mode. 


53: The language interface version is invalid. 


Explanation: An application tried to access a file containing variable-length records with a 
language interface from Btrieve v3.15 or earlier. To access files with variable- 
length records, you must use a v4.x or later interface. 


54: The variable-length portion of the record is corrupt. 


Explanation: During a Get or Step operation, Btrieve cannot read all or part of the variable- 
length portion of a record. Btrieve returns as much data as possible to the 
application. This status code usually indicates one or more pages used to store 
variable length records is corrupt. Use BUTIL -RECOVER to recover as much 
data as possible. 


55: The application specified an invalid attribute for an autoincrement key. 


Explanation: The application tried to specify either the segmented or duplicate attribute for 
an autoincrement key type. An autoincrement key cannot be part of a 
segmented key and cannot allow duplicates. 


56: An index is incomplete. 


Explanation: An index can be damaged if a Create Index operation (31) or a Drop Index 
operation (32) is interrupted before it runs to completion. Perform a Drop 
Index operation to completely remove the damaged index from the file, and 
then rebuild the index with the Create Index operation, if so desired. 
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58: The compression buffer length is too short. 


Explanation: 


The application tried to read or write a record that is longer than the value 
specified for the size of the compression buffer. Reconfigure Btrieve using the 
Setup utility, specifying a higher value for the Largest Compressed Record 
Size option. 


59: The specified file already exists. 


Explanation: 


This status code is returned for the Create operation if the application specified 
-1 in the key number parameter and the name of an existing file in the key 
buffer parameter. If you want to overwrite the existing file, remove the -1 from 
the key number parameter. If you want to preserve the existing file, alter the 
filename specified in the key buffer parameter. 


60: The specified reject count has been reached. 


Explanation: 


Btrieve rejected the number of records specified by the reject count before a 
Get Next Extended, Get Previous Extended, Step Next Extended, or Step 
Previous Extended operation found the requested number of records that 
satisfy the filtering condition. Check the first two bytes returned in the data 
buffer for the number of records that were retrieved. 


61: The work space is too small. 


Explanation: 


The Get Next Extended, Get Previous Extended, Step Next Extended, and 
Step Previous Extended operations use a buffer as work space. This status 
code indicates that the work space (set by default to 16 KB) is not large enough 
to hold the filtering data buffer structure and the largest record to be received. 


62: The descriptor is incorrect. 


Explanation: 


The descriptor (data buffer structure), which is passed for a Get Next 
Extended, Get Previous Extended, Step Next Extended, or Step Previous 
Extended operation, is incorrect. The descriptor length (the first two bytes of 
the data buffer) on the extended operation call must be the exact length of the 
descriptor. This requirement does not apply to the data buffer length option, 
which can still be declared longer than necessary. 


On a Get Direct/Chunk operation, the descriptor structure in the data buffer is 
incorrect, or it is inconsistent (either internally or in respect to the data buffer 
length). See the discussion of the Get Direct/Chunk operation in Chapter 4 of 
the Btrieve Programmer's Manual for information about the correct descriptor 
format. 


172 Btrieve Installation and Operation 


63: The data buffer parameter specified on an Insert Extended operation is invalid. 


Explanation: An Insert Extended operation provided an invalid buffer. Either the buffer 
length is less than 5 bytes, or the number of records specified is 0. Correct the 
buffer length or the number of records. 


64: The filter limit has been reached. 


Explanation: During a Get Next Extended, Get Previous Extended, Step Next Extended, or 
Step Previous Extended operation, a rejected record was reached; no other 
record can satisfy the given filtering condition, going in the direction that the 
operation specified. This is applicable only if the first segment of the key that 
the key number specified is also used as the first term of the filtering field. 


65: The field offset is incorrect. 


Explanation: The field offset in the extractor of a Get Next Extended, Get Previous 
Extended, Step Next Extended, or Step Previous Extended operation is invalid 
based on the length of the retrieved record. Make sure that the field offset is a 
valid value (from 0 through the record length minus 1). 


66: The maximum number of open databases has been exceeded. 


Explanation: The application has tried to open too many SQL databases configured for 
referential integrity checking at one time. The maximum number of databases 
that can be opened concurrently for referential integrity checking is a 
configurable startup option for Btrieve. The default is set to 20. 


Refer to your NetWare SQL documentation for more information on 
referential integrity. 


67: Btrieve cannot open the SQL data dictionaries. 


Explanation: This status code may indicate that an application opened a data file containing 
referential integrity definitions but Btrieve cannot open one of the NetWare 
SQL data dictionary files (FILE.DDF or RELATE.DDF) or the configuration 
file (DBNAMES.CFG). 


Be sure that DBNAMES.CFG is present in the SYS:SYSTEM directory, and 
that the FILE.DDF and RELATE.DDF files for that named database are 
placed in the dictionary location that the Setup utility defines. Refer to your 
NetWare SQL documentation for more information on referential integrity. 
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68: Btrieve cannot perform the RI Delete Cascade operation. 


Explanation: 


Btrieve cannot enforce the Delete Cascade rule on a file under referential 
integrity control because the record that the application attempted to delete has 
more than 16 levels of descendants. Delete records from the lower levels, and 
then try again to delete the record that the application was attempting to delete 
initially. Refer to your NetWare SQL documentation for more information on 
referential integrity. 


69: The Delete operation cascades to a record in a file that is damaged. 


Explanation: 


The application encountered an error while Btrieve was attempting to enforce 
the Delete Cascade rule in response to a Delete operation. This status code 
indicates that the related file has been damaged and must be recreated. 


Refer to your NetWare SQL documentation for more information on 
referential integrity and the Delete Cascade rule. 


71: There is a violation of the RI definitions. 


Explanation: 


If you have attempted an Insert operation on a file under referential integrity 
control, you may receive this status code if a foreign key value in the record 
to be inserted does not have a corresponding primary key in the referenced 
file. 


If you are performing an Update operation, there are two possible causes for 
this status code: 


+ You are attempting to change the value of a primary key. 


+ You are attempting to change the value of a foreign key to a value that 
does not exist for the defined primary key. 


If you have attempted a Delete operation, the Restrict rule is being enforced, 
and a primary key value in the record you are trying to delete references a 
foreign key in the referenced file. Refer to your NetWare SQL documentation 
for more information on referential integrity. 


72: Btrieve cannot open the RI referenced file opened. 


Explanation: 


The referenced file cannot be found at the location that FILE.DDF and 
DBNAMES.CFG specify. This status code is returned only on a first attempt 
to delete or insert in a file under referential integrity control, or on a first 
attempt to update when that operation would change a foreign key in the 
specified file. 
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Be sure that the referenced file is in one of the data file locations that the Setup 
utility specified. Also, verify that the file location does not contain a drive 
letter. Refer to your NetWare SQL documentation for more information on 
referential integrity. 


73: The RI definition is out of sync. 


Explanation: 


You have attempted to open a file for which the referential integrity definition 
either disagrees with the definition in RELATE.DDF or refers to a database 
not found in DBNAMES.CEG. This status code can also occur on an Insert or 
Delete operation, or an Update operation that would change a foreign key. 


Run the NetWare SQL RIUTIL utility, and use the CHECK command. For 
information on the RIUTIL utility and on referential integrity, refer to your 
NetWare SQL documentation. 


74: Btrieve aborted the transaction. 


Explanation: 


This is an informative status code. Btrieve replaced an End Transaction 
operation with an Abort Transaction after detecting an error for a Transaction 
Tracking System (TTS) file inside the transaction. In addition, Btrieve 
executed the Abort Transaction operation. 


76: There is a conflict on the referenced file. 


Explanation: 


The application has attempted to perform an Update, Insert, or Delete 
operation on an RI-controlled file that references another file. The application 
cannot open the referenced file for referential integrity checking because it is 
already opened in Exclusive mode. Wait until the referenced file is closed or 
is opened in a mode other than Exclusive, and then retry the operation. Refer 
to your NetWare SQL documentation for more information on referential 
integrity. 


77: The application encountered a wait error. 


Explanation: 


Either a wait lock bias is specified for an operation but another user has locked 
the requested resource, or the application is currently processing a wait 
transaction and tried to access a file that another user has locked. 


When you are using the Btrieve Requester to access Btrieve, the Requester 
waits and retries if a requested resource is locked. When a server-based 
application, such as NetWare SQL, is accessing Btrieve and the requested 
resource is locked, a wait is also required. In this case, Btrieve would be 
expected to perform the wait. Since this would occupy Btrieve and lock out 
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other users who might be trying to release the requested resource, Btrieve does 
not perform the wait. Instead, it returns a Status Code 77, and the server-based 
application must retry later. 


78: Btrieve detected a deadlock condition. 


Explanation: 


The application should clear all resources (for example, by aborting or ending 
the transaction, or releasing all record locks) before proceeding. This breaks 
the deadlock, allowing other applications to access the resources for which 
they are waiting. 


79: A programming error occurred. 


Explanation: 


Although very rare, it is possible to receive this status code when there is a 
malfunction that Btrieve cannot specifically detect or from which Btrieve 
cannot recover. Retry the operation again. If the error persists, there may be a 
system corruption; try to clear the system by restarting, and then try the 
operation again. 


80: The application encountered a record-level conflict. 


Explanation: 


Btrieve did not perform the Update or Delete operation because of a record- 
level conflict. For example, station A reads a record, station B reads the same 
record and updates it, and then station A attempts to update the record. The 
application should reread the record prior to resending an Update or Delete 
operation. 


81: The application encountered a lock error. 


Explanation: 


This status code can result from one of the following conditions: 


+ The Btrieve lock table is full. Decrease the number of locks that the 
application uses, or use the Setup utility to specify a higher value for the 
Number of Locks option. 


¢ The application tried to unlock one record that is locked with a multiple 
record lock, but the record position stored in the data buffer does not 
correspond to any record locked in the associated file. 


¢ The application tried to unlock a single-record lock with a multiple- 
record lock or vice-versa. 
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82: The application lost positioning. 


Explanation: | When performing a Get Next or Get Previous operation on a key with 
duplicates, the application tried to retrieve a record that was deleted or whose 
key value was modified by another application. Use a Get Equal or a Get 
Direct/Record operation to reestablish positioning. 


83: The application attempted to change a record that was read outside the 
transaction. 


Explanation: The application tried to update or delete a record within a transaction, but the 
record was not read within the transaction. The application must read the 
record within the transaction before attempting to modify the data. 


84: The record is locked. 


Explanation: The application tried to apply a nowait lock on a record that is currently locked 
by another application, or the application tried to access a file in a nowait 
transaction while another application holds an active record lock(s) in that file. 


This status code can also occur if the application tried to update or delete a 
record locked by another application. 


The application can use either of the following recovery methods: 


¢ Retry the operation until it is successful. Under light-to- moderate 
network use, this may be the simplest and quickest solution. 


+ Use the wait option (+100/+300) instead of the nowait option. 


Btrieve may return this status code on an Insert operation when it attempts to 
lock an index page to update the key value specified for a newly inserted 
record. If another user has already locked the record in question, then Btrieve 
returns a Status Code 84 when it attempts to update the key value. Have your 
application check for this status code and retry the operation if the status code 
is returned. 
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85: The file is locked. 


Explanation: 


Any of the following can cause this status code to occur: 


+ 


Client-based Btrieve has a file open, and another workstation that has the 
Requester loaded tries to open the same file. Btrieve cannot open the file 
since it cannot obtain exclusive access. The workstation that has the 
Requester loaded receives Status Code 85. 


Another workstation has the Requester loaded and has a file open, and 
client-based Btrieve tries to open the same file. 


A file is in transition into continuous operation mode. A retry will 
eventually work. 


While one user has a file locked in an exclusive transaction, another user 
attempts to lock all or part of that file. 


A user has two Btrieve files with the same filename but different 
extensions (for example, INVOICE.HDR and INVOICE.DET). One file 
is open and in continuous operation mode, causing Btrieve to generate a 
delta file (for example, INVOICE."). Btrieve returns Status Code 85 if 
the user attempts to open the second file. 


86: The file table is full. 


Explanation: 


Using the Setup utility, specify a higher value for the Number of Open Files 
configuration option. For more information, refer to “Installing and 
Configuring Btrieve” on page 43. 


87: The handle table is full. 


Explanation: 


This status code is applicable only in the server-based Btrieve environment. 
Using the Setup utility, specify a higher value for the Number of Handles 
configuration option. For more information, refer to “Installing and 
Configuring Btrieve” on page 43. 
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88: The application encountered an incompatible mode error. 


Explanation: | When you are using continuous operation, this status code can indicate any of 
the following: 


+ You have attempted to remove a file from continuous operation, but the 
file is not in a continuous state. 


+ You have attempted to include two files that have the same name but 
different extensions in continuous operation. 


+ You have attempted to include a file in continuous operation, but the file 
is already in a continuous state. 


+ Ifan application opens a file in Exclusive mode, all other applications get 
this status code when they try to open the same file in any mode. 


¢ If an application opens a file in any mode other than Exclusive, all other 
applications get this status code when they try to open the same file in 
Exclusive mode. 


91: The application encountered a server error. 
Explanation: You can receive this status code in the following situations: 


+ The Requester cannot establish a session with the server. Either Btrieve is 
not loaded or the server is not active. 


+ The setting for the Number of Remote Sessions configuration option is 
too low. Return to the Setup utility and specify a higher value for this 
option. 


+ An application specified a path for a file and did not include the volume 
name in the path. 


92: The transaction table is full. 


Explanation: The maximum number of active transactions was exceeded. Using the Setup 
utility, specify a higher value for the Number of Transactions configuration 
option. For more information, refer to “Installing and Configuring Btrieve” on 
page 43. 


93: The record lock types are incompatible. 


Explanation: The application tried to mix single-record locks (+100/+200) and multiple- 
record locks (+300/+400) in the same file at the same time. All locks of one 
type must be released before a lock of the other type can be executed. 
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94: The application encountered a permission error. 


Explanation: 


You can receive this status code in the following situations: 


¢ The application tried to open or create a file in a directory without the 
proper privileges. Btrieve does not override the network privileges 
assigned to users. 


+ The designated server is in the server routing table, but your particular 
workstation is not logged into that server. 


+ Served-based BREQUEST and client-based Btrieve are trying to access 
the same file at the same time. 


¢ Btrieve was unable to log in to the NetWare Runtime server using the 
given username. The user either does not exist on the Runtime server or 
does not have the appropriate rights to open or create a file. 


95: The session is no longer valid. 


Explanation: 


The previously established session is no longer active due to an error at the 
workstation, at the file server, or on the network. Verify that the workstation 
is still attached to the server, and then unload and reload the Btrieve Requester 
as discussed in “DOS Requester” on page 71. 


This status code can also indicate that the maximum number of sessions for 
Btrieve has been reached. Use the Communication Statistics option of the 
Btrieve Monitor utility to see if the maximum number of sessions has been 
reached. If so, use the Setup utility to specify a higher value for the Number 
of Remote Sessions configuration option. For more information, refer to 
“Installing and Configuring Btrieve” on page 43. 


96: A communications environment error occurred. 


Explanation: 


You tried to attach to Btrieve on a server but the SPX connection table or the 
Btrieve client table is full. Use the Setup utility to specify a higher value for 
the Number of Remote Sessions configuration option. For more information, 
refer to “Installing and Configuring Btrieve” on page 43. 


When this status is returned to an NLM application, verify that all clients are 
being properly reset. 
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97: The communications buffer is too small. 


Explanation: The application tried to read or write a record that is longer than the current 
settings for Btrieve or the Btrieve Requester allow, as follows: 


¢ For an Update, Insert, or Create operation, the application receives this 
status code if the data buffer length it specifies for the record exceeds 
Btrieve's internal communications buffer length. 


+ Fora Get, Step, or Stat operation, the application receives this status code 
if Btrieve's internal communications buffer is shorter than the length of 
the data Btrieve would return, regardless of the data buffer length 
specified in the application. 


+ Fora Get Chunk or Update Chunk operation, the total size of the retrieved 
or updated chunk exceeds Btrieve's internal communications buffer 
length. 


Btrieve calculates the length of its communications buffer using as a base the 
values of the Largest Record Size option (from the Setup utility) and the Data 
Message Length (/D) option (specified when the Btrieve Requester and/or 
BSPXCOM was loaded). 


To increase the size of the communications buffer, use the Setup utility to 
specify a higher value for the Largest Record Size option. Then, reload the 
Btrieve Requester, and specify a higher value for the Data Message Length (/ 
D) option. For more information, refer to “Installing and Configuring Btrieve” 
on page 43 


98: Btrieve detected an internal transaction error. 


Explanation: Btrieve detected an error while executing the operation on a NetWare TTS file. 
The application can perform only an Abort Transaction operation at this point. 


99: The Requester cannot access the NetWare Runtime server. 


Explanation: The DOS Requester returns this status code when NetWare Runtime server 
support is enabled (/C:1) and the Requester either detects no existing 
connection or cannot find a valid login username. If the Requester cannot find 
a login username other than SUPERVISOR, there is no valid name to pass. 


100: No cache buffers are available. 


Explanation: Btrieve has used all the cache buffers it allocated at load time. Using the Setup 
utility, you can increase the value for the Cache Allocation configuration 
option. Alternatively, you can change the Number of Remote Sessions 
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configuration option to decrease the number of concurrent Btrieve users. For 
more information, refer to “Installing and Configuring Btrieve” on page 43. 


101: Insufficient operating system memory is available. 


Explanation: 


There is not enough operating system memory available to perform the 
requested operation. Decrease the value for the Cache Allocation 
configuration option (using the Setup utility), decrease the number of 
concurrent Btrieve users (using the Number of Remote Sessions configuration 
option in the Setup utility), or add memory to the server. For more information 
on the configuration options, refer to “Installing and Configuring Btrieve” on 
page 43. 


102: Insufficient stack space is available. 


Explanation: 


Btrieve has run out of stack space. To increase the amount of stack space 
available to your application, relink the application, setting the stack size to a 
higher value. Only the NLM applications calling Btrieve on the local server 
get this message. 


103: The chunk offset is too big. 


Explanation: 


A Get Direct/Chunk operation has specified an offset beyond the end of the 
record, either explicitly or through the use of the next-in-record bias to the 
subfunction value. Unless Btrieve returns this status while processing the first 
chunk, the operation was partially successful. Check the data buffer length 
parameter immediately after the call to see how much data (and therefore how 
many chunks) Btrieve retrieved. 


This code can also be returned by the Update Chunk operation when the 
specified offset is more than one byte beyond the end of the record. However, 
in this situation, Status Code 103 indicates that Btrieve made no changes to 
the record. 


104: The locale information could not be found. 


Explanation: 


The Create or Create Index function returns this status code to indicate that the 
operating system was not able to return a collation table for the country ID and 
code page specified. Check that the application specified the locale's country 
ID and code page correctly and that the operating system is configured to 
support the country ID and code page. 
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105: The file cannot be created with Variable-tail Allocation Tables (VATs). 


Explanation: The application specified that a Btrieve file should be created with Variable- 
tail Allocation Tables (VATs); however, the application failed to specify that 
the file was to use variable-length records (a precondition for files to use 
VATs). This status applies to key-only files as well as regular data files. 


106: The operation cannot get the next chunk. 


Explanation: The application called the Get Direct/Chunk operation to retrieve a chunk 
from a record and used the next-in-record bias on the descriptor subfunction. 
However, after the application established its positioning in the record (but 
prior to this call), the target record was deleted. 


107: Chunk updates/retrievals cannot be performed on the file. 


Explanation: The application tried to use either a Get Direct/Chunk operation or an Update 
Chunk operation on a pre-v6.0 formatted file. 


Client-Based Btrieve for OS/2 and Windows Status 
Codes 


Client-based Btrieve may return the following status codes in an OS/2 or 
Windows environment. 


1001: The Multiple Locks option is out of range. 


Explanation: |The number specified for the Multiple Locks configuration option must be 
between 1 and 255, inclusive. 


1002: Btrieve cannot allocate the memory needed. 


Explanation: Make sure that the workstation has enough memory to load all the programs 
it requires. 


1003: The Memory Size is too small. 


Explanation: | Make sure the value for the Memory Size configuration option is large enough 
to accommodate the required cache size. 
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1004: The Page Size option is out of range. 


Explanation: The value of the Page Size configuration option must be an even multiple of 
512, and it must be between 512 and 4,096, inclusive. 


1005: The Pre-Image File Drive option is invalid. 


Explanation: You must specify a valid drive letter for the Pre-Image File Drive 
configuration option. 


NOTE: Pre-image files are used only for files created by Btrieve versions earlier 
than v6.x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x Format 
configuration option set to Yes. 


1006: The Pre-Image Buffer Size option is out of range. 


Explanation: The Pre-Image Buffer Size configuration option must be between 1 and 64, 
inclusive. 


NOTE: Pre-image files are used only for files created by Btrieve versions earlier 
than v6x, or by v6.x if it was loaded with the Create Btrieve Files in Pre v6.x Format 
configuration option set to Yes. 


1007: The Open Files option is out of range. 


Explanation: The Open Files configuration option must be between 1 and 255, inclusive. 


1008: The Configuration options are invalid. 


Explanation: The configuration options specified contain invalid or unidentifiable values. 
For more information on configuration options, refer to the installation and 
operation manual for your operating environment. 


1009: The Transaction Filename option is invalid. 


Explanation: The filename specified for the Transaction Filename configuration option is 
not valid. Check to make sure that the transaction filename is correct. 


1011: The Compression Buffer Size specified is out of range. 


Explanation: The Compression Buffer Size configuration option must be between 1 and 64, 
inclusive. 


184 Birieve Installation and Operation 


1013: The task table is full (Windows only). 


Explanation: The Btrieve DLL may return this status code if the task entry table is full. You 
can remedy this situation by increasing the number of available task entries; 
use the tasks initialization option (tasks=xxx) under the [BTRIEVE] or 
[BREQUESTDPMI] headings in NOVDB.INI. The minimum value for this 
option is 1; the maximum value is 255. 


1014: The application encountered a stop warning. 


Explanation: _WBTRVSTOP ( ) returns this status code if the application still has open files 
or an active transaction. The application must close all files and end all 
transactions before calling WBTRVSTOP ( ). 


1015: A pointer parameter is invalid. 


Explanation: One of the pointer parameters passed into Btrieve is invalid. 


1016: Btrieve is already initialized. 


Explanation: The Btrieve DLL may return this status code if an attempt is made to initialize 
Btrieve when it is already initialized. To reinitialize Btrieve, close all files, 
end/abort all transactions, and call WBTRVSTOP ( ) before calling the 
initialization function. 


1017: The resource file WBTRVRES.DLL cannot be found. 


Explanation: The WBTRCALL.DLL returns this status code when it cannot find the 
resource file WBTRVRES.DLL. You can remedy this situation by placing a 
copy of the WBTRVRES.DLL file in the same directory as the 
WBTRCALL.DLL file. 
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Btrieve Requesters Status Codes 


This section lists the status codes that the Btrieve Requesters may generate. 


2001: The memory allocation is insufficient. 


Explanation: In an OS/2 environment, the Requester cannot allocate enough memory for the 
parameters specified with the BRQPARMS environment variable. In a DOS 
environment, reduce the value specified for the /D configuration option. 


2002: The option is invalid or out of range. 


Explanation: In an OS/2 environment, either one of the options specified with the 
BRQPARMS environment variable is invalid (such as /P instead of /D) or the 
value specified for a parameter is out of range. Check the SET BRQPARMS 
statement to make sure it is correct. 


2003: The Requester does not allow local access to the specified file. 


Explanation: The application attempted to access a file stored on a local drive. The version 
of WBTRCALL.DLL installed at the workstation does not allow access to 
local files. 


2004: SPX is not installed. 


Explanation: Install the NetWare SPX v1.3 or later communications software for OS/2. 


2005: An incorrect version of SPX is installed. 


Explanation: Install the NetWare SPX v1.3 or later communications software for OS/2. 


2006: There is no available SPX connection. 


Explanation: SPX has already established the maximum number of sessions it can handle. 
To increase the maximum, edit the NET.CFG file. Refer to your NetWare 
documentation for more information on NET.CFG. 


2007: A pointer parameter is invalid. 


Explanation: One of the pointer parameters passed to Btrieve is invalid. Check the program 
to ensure that the pointer parameters are correct. 


186 Birieve Installation and Operation 


Btrieve NLM Messages 


The following messages are sent by the Btrieve NLM. 


BTRIEVE-6.1-1: The value specified for the Cache Allocation option is invalid. 


Explanation: The Btrieve NLM returns this message when the value specified for the Cache 
Allocation option is invalid. Use the Setup utility and specify a value between 
32 through 64,000 for this option. 


BTRIEVE-6.1-2: The value specified for the Largest Compressed Record Size option 
is invalid. 


Explanation: The Btrieve NLM returns this message when the value specified for the 
Largest Compressed Record Size option is invalid. Return to the Setup utility 
and specify a valid value for the Largest Compressed Record Size option. 


BTRIEVE-6.1-4: The value specified for the Number of Open Files option is invalid. 


Explanation: The Btrieve NLM returns this message when the value specified for the 
Number of Open Files option is invalid. Use the Setup utility and specify a 
value between 1 and 64,000 for this option. 


BTRIEVE-6.1-7: The value specified for the Number of Handles option is invalid. 


Explanation: The Btrieve NLM returns this message when the value specified for the 
Number of File Handles option is invalid. Use the Setup utility and specify a 
value between 1 and 64,000 for this option. 


BTRIEVE-6.1-9: The value specified for the Number of Remote Sessions option is 
invalid. 


Explanation: The Btrieve NLM returns this message when the value specified for the 
Number of Remote Sessions option is invalid. Use the Setup utility and 
specify a value between | and 64,000 for this option. 


BTRIEVE-6.1-12: The value specified for the -option option is invalid. 


Explanation: The Btrieve NLM returns this message when the value for an option is not 
valid. Return to the BSTART.NCF file and enter the correct value. 
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BTRIEVE-6.1-13: The option specified is not a valid option. 


Explanation: The Btrieve NLM returns this message when the option specified is not a valid 
option. Return to the BSTART.NCF file and remove the invalid option. 


BTRIEVE-6.1-14: Continuous operation is active on one or more files. Roll-in could 
not be completed. Please free some disk space if you wish to end continuous 
operation before unloading the BTRIEVE NLM. 


Explanation: The Btrieve NLM returns this message when the server has insufficient disk 
space to allow Btrieve to complete the roll in. Free some disk space in order 
to end continuous operation and unload the Btrieve NLM. 


BTRIEVE-6.1-16: The server has insufficient memory to complete the operation. 


Explanation: The Btrieve NLM returns this message when the server has insufficient 
memory to allow Btrieve to load as it is configured. Use the Setup utility to 
reconfigure Btrieve to use less memory, or unload any unnecessary NLMs. 


BTRIEVE-6.1-17: The header in log file xxxx is invalid. 


Explanation: The Btrieve NLM returns this message when the header in log file xxxx is 
invalid. The file xxxx is expected to be a log file according to BLOG.CFG but 
it is not. If you receive this message, either delete file xxxx and create a new 
log file, or change BLOG.CFG to specify a different log file. 


BTRIEVE-6.1-18: The log file xxxx cannot be created in the location specified. 


Explanation: The Btrieve NLM returns this message when log file xxxx cannot be created 
in the location specified. Check that the disk is not full and that the user has 
rights to create and write to log file xxxx. 


BTRIEVE-6.1-19: Logging is not active for file xxxx; check the file specification in 
BLOG.CFG. 


Explanation: The Btrieve NLM returns this message when logging is not active for the file 
xxxx; check the file specification in BLOG.CFG. This message is always 
displayed with the Invalid Header in Log File xxxx message or the Unable to 
Create Log File xxxx message. 
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BTRIEVE-6.1-20: The log file xxxx cannot be written. Check disk space. 


Explanation: The Btrieve NLM returns this message when log file xxxx cannot be written. 
Check the disk space. If the disk is full, free some space by deleting any 
unnecessary files. 


BTRIEVE-6.1-21: Logging has stopped for file xxxx. 


Explanation: The Btrieve NLM returns this message when logging has stopped for file xxxx. 
The log file xxxx cannot be written. Check the disk space. If the disk is full, 
free some space by deleting unnecessary files. 


BTRIEVE-6.1-22: Files have been found in continuous operation; files in continuous 
operation are being rolled in. 


Explanation: The Btrieve NLM returns this message when files have been found in 
continuous operation; files in continuous operation are being rolled in 
(updated). 


BTRIEVE-6.1-23: Files have been found in continuous operation; an error was 
detected while rolling in these files. 


Explanation: The Btrieve NLM detected files in continuous operation; an error was detected 
while rolling in (updating) these files. Check to see if the disk is full or if any 
other disk problems exist. 


BTRIEVE-6.1-24: Files have been found in continuous operation; these files have 
been successfully rolled in. 


Explanation: The Btrieve NLM detected files in continuous operation; these files have been 
successfully rolled in (updated). 


BTRIEVE-6.1-25: The file xxxx is rolling back. 


Explanation: The Btrieve NLM returns this message when the file xxxx is rolling back. 
(Rolling back refers to aborting a transaction and undoing all changes made to 
the database during the transaction, thus restoring the database to the state it 
was in before the transaction began.) 


BTRIEVE-6.1-26: The transaction roll back cannot be completed. Check the memory 
available on the server. 


Explanation: The Btrieve NLM returns this message when it is rolling back the transaction 
but the transaction roll back cannot be completed. (Rolling back refers to 
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aborting a transaction and undoing all changes made to the database during the 
transaction, thus restoring the database to the state it was in before the 
transaction began.) Check the memory available on the server. Free memory 
by unloading NLMs or reconfiguring NLMs to use less memory. 


BTRIEVE-6.1-27: The transaction control file cannot be created. 


Explanation: The Btrieve NLM returns this message when the transaction control file 
(BTRIEVE.TRN) cannot be created. Btrieve was unable to open or create 
SYS:SYSTEM/BTRIEVE.TRN. Make sure that no user has that file open. 


Btrieve Requester Messages 


The following messages are sent by the Btrieve DOS Requester 
(BREQUEST.EXE). 


BREQUEST-6.1-1: The message file xxxx is invalid; BREQUEST cannot be loaded. 


Explanation: The Btrieve Requester returns this message when the message file is invalid. 
Specify a valid message file so that BREQUEST.EXE can be loaded. 


BREQUEST-6.1-3: The option specified is not a valid option. 


Explanation: The Btrieve Requester returns this message when the option specified is not a 
valid option. Specify a valid option. 


BREQUEST-6.1-4: The value specified for the Data Message Length (/d) option is 
invalid. 


Explanation: The Btrieve Requester returns this message when the value specified for the 
Data Message Length (/D) option is invalid. Specify the /D option as /D:n, 
where n is an integer. 


BREQUEST-6.1-5: The workstation has insufficient memory to load BREQUEST. 


Explanation: The Btrieve Requester returns this message when the workstation has 
insufficient memory to load the Requester. Unload unnecessary programs or 
try a smaller value for the /D option. 
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BREQUEST-6.1-6: BREQUEST is already loaded. 


Explanation: The Btrieve Requester returns this informational message to indicate that 
BREQUEST.EXE 1s already loaded. 


BREQUEST-6.1-7: XQL or NSREQ is already loaded; BREQUEST must be loaded first. 


Explanation: The Btrieve Requester returns this message when XQL or NSREQ is already 
loaded; the DOS Requester must be loaded first. Unload XQL or NSREQ and 
then load the DOS Requester. 


BREQUEST-6.1-8: DOS 2.00 or greater is not loaded; load DOS 2.00 or greater. 


Explanation: The Btrieve Requester returns this message. DOS v2.x or later is not loaded; 
you must load DOS v2.x or later to proceed. 


BREQUEST-6.1-9: The SPX.COM file is not loaded; load the file SPX.COM. 


Explanation: The Btrieve Requester returns this message when the file SPX.COM is not 
loaded. Load SPX.COM. 


BREQUEST-6.1-10: The function SPXInitialize returned an error. Make sure the file 
IPX.COM is loaded. 

Explanation: The Btrieve Requester returns this message when the SPXInitialize function 

encounters an error. You must make sure that the file IPX.COM is loaded. 

BREQUEST-6.1-11: The IPX socket table is full. 

Explanation: The Btrieve Requester returns this message when the IPX socket table is full. 
BREQUEST-6.1-13: The value specified for the Runtime server support (/C) option is 
invalid. 


Explanation: The Btrieve Requester returns this message when an invalid value is specified 
for the NetWare Runtime Server Support option (/C). Specify this option in 
one of these forms: 


/C:0 To disable NetWare Runtime server support. 


10:1 To enable NetWare Runtime server support. 
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To authenticate requests on the NetWare Runtime server, provide a username and password, 
separating them with commas, as follows: 


/C:1,username,password 


For more information about this option, see “Configuring and Using the 
Requesters” on page 71. 


Btrieve Message Router Messages 


The following messages are sent by BROUTER. 


BROUTER-6.1-1: The server has insufficient memory to execute BROUTER. 


Explanation: BROUTER returns this message when the server has insufficient memory to 
load the file BROUTER.NLM. Free some memory by unloading NLMs or 
reconfiguring NLMs to use less memory. 


BROUTER-6.1-2: The value specified for a configuration option is invalid. 


Explanation: BROUTER returns this message when the value specified for a configuration 
option is invalid. Reload BROUTER.NLM using valid options. 


BROUTER-6.1-3: An internal error has occurred; the SPXOpenSocket function failed. 


Explanation: BROUTER returns this message if an internal diagnostic error occurs. The 
SPXOpenSocket function failed. Another NLM may be using the socket 
number reserved for BROUTER. If you receive this message, unload all other 
NLMs and then load BTRIEVE.NLM and BROUTER.NLM. Finally, reload 
the other NLMs. This process reveals the NLM that is using BROUTER's 
socket number. 


BROUTER-6.1-6: BROUTER is loaded. 


Explanation: BROUTER returns this message to indicate that BROUTER.NLM is now 
loaded. 
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Btrieve SPX Communications Messages 


The following messages are sent by the Btrieve SPX communications module 
(BSPXCOM.NLM). 


BSPXCOM-6.1-1: The option specified is not a valid option. 


Explanation: The Btrieve SPX communications module returns this message when the 
option specified is not a valid option. Specify a valid option. 


BSPXCON-6.1-2: The server has insufficient memory to execute BSPXCOM. 


Explanation: The Btrieve SPX communications module returns this message if the server 
has insufficient memory to load the file BSPXCOM.NLM. If you receive this 
message, you must free memory by unloading NLMs or reconfiguring NLMs 
to use less memory. 


BSPXCON-6.1-3: An internal error has occurred. BSPXCOM detected a semaphore 
allocation failure. 


Explanation: The Btrieve SPX communications module returns this message when an 
internal diagnostic error occurs. BSPXCOM detected a semaphore allocation 
failure. 


BSPXCOM-6.1-4: The Service Request Block (SRB) function code nn contains invalid 
data. Check for an incompatible version of the file BSPXCOM.NLM. 


Explanation: The Btrieve SPX communications module returns this message if the Service 
Request Block (SRB) function code contains invalid data. Check that 
BSPXCOM's version is compatible with the version number of the 
workstation's Btrieve Requester. 


BSPXCOM-6.1-6: An internal error has occurred. The session was not found in 
ConnTable. 


Explanation: The Btrieve SPX communications module returns this message when an 
internal diagnostic error occurs. The session was not found in ConnTable. 


BSPXCOM-6.1-7: Another NLM is using the socket number reserved for BSPXCOM. 


Explanation: The Btrieve SPX communications module detected another NLM using the 
socket number reserved for BSPXCOM. Unload all other NLMs and then load 
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BTRIEVE.NLM and BSPXCOM.NLM. Finally, reload the other NLMs. This 
process reveals the NLM that is using BSPXCOM's socket number. 


BSPXCON-6.1-8: An SPX-level receive I/O error (hexadecimal code nn) has occurred. 
The connection has been lost. 


Explanation: The Btrieve SPX communications module returns this message when an SPX- 
level receive I/O error occurs. The connection has been lost. 


BSPXCOM-6.1-9: An SPX-level send I/O error (hexadecimal code nn) has occurred. 
The connection has been lost. 


Explanation: The Btrieve SPX communications module returns this message when an SPX- 
level send I/O error occurs. The connection has been lost. 


BSPXCOM-6.1-10: An internal error (hexadecimal code nn) has occurred. BSPXCOM 
detected a Dequeue error. 


Explanation: The Btrieve SPX communications module returns this message when an 
internal diagnostic error (a dequeue error) occurs. 


BSPXCOM-6.1-11: Bad connection ID detected on receive. The SPX connection was 
lost after the initial request began. 


Explanation: The Btrieve SPX communications module detected a bad connection ID on a 
receive. The SPX connection was lost after the initial request began. No action 
1s needed if this message appears occasionally when you restart your 
workstation. However, if this message appears frequently when you have not 
restarted your workstation, you must increase your workstation's SPX 
Timeout parameter. Also, you can check for NLMs monopolizing the CPU 
time. 


BSPXCOM-6.1-12: Bad connection ID detected on send. The SPX connection was lost 
after the initial request began. 


Explanation: The Btrieve SPX communications module returns this message when it 
detects a bad connection ID ona send. The SPX connection was lost after the 
initial request began. No action is needed if this message appears occasionally 
when you reboot your workstation. However, if this message appears 
frequently when you have not restarted your workstation, you must increase 
your workstation's SPX Timeout parameter. Also, you can check for NLMs 
monopolizing the CPU time or for a hardware failure. 
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BSPXCOM-6.1-13: An error (hexadecimal code nn) was detected while trying to 
establish an SPX session requested by a remote workstation. 


Explanation: The Btrieve SPX communications module detected an internal diagnostic 
error while it was trying to establish an SPX connection requested by a remote 
workstation. 


BSPXCOM-6.1-15: The request for statistics from the Btrieve Monitor utility was not 
recognized. Check for an incompatible version of the utility or BSPXCOM. 


Explanation: The Btrieve SPX communications module returns this message if the request 
for statistics from the Btrieve Monitor utility was not recognized. Check for 
an incompatible version of the utility or BSPXCOM. 


BSPXCOM-6.1-16: The session was rejected; the session limit was reached. Increase 
the value specified for the Number of Remote Sessions option. 


Explanation: The Btrieve SPX communications module returns this message to indicate the 
session was rejected because the session limit was reached. Increase the value 
specified for the Number of Remote Sessions configuration option. Unload 
and then reload BSPXCOM.NLM so that the new value can be used. (For 
more information about this option, refer to “Installing and Configuring 
Btrieve” on page 43.) 


BSPXCOM-6.1-17: An internal error has occurred. BSPXCOM did not recognize the 
GET_EIM_STATS function. 


Explanation: The Btrieve SPX communications module returns this message when an 
internal diagnostic error occurs. BSPXCOM did not recognize the 
GET_EIM_STATS function. Check to see 1f the version of BSPXCOM is 
compatible with that of the Btrieve Monitor utility (BTRMON.NLM). 


Maintenance Utility Messages 


The following messages are sent by the Maintenance utility (BUTIL.NLM). 


BUTIL-6.10-1: The keyword compression is no longer supported. Use truncate. 


Explanation: The compress keyword is no longer used in description files. However, you 
may reduce the file size for files that contain variable-length records by 
specifying y for the truncate keyword. The truncate keyword has no effect 
unless the file contains variable-length records. 
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BUTIL-6.10-2: An error occurred while BUTIL was accessing the description file. 


Explanation: The Maintenance utility returns this message when an error occurs during 
access of a description file. Make sure the file has not been corrupted and that 
the information it contains is properly formatted. 


BUTIL-6.10-6: The BUTIL command is invalid. 


Explanation: The Maintenance utility returns this message when the syntax of the command 
you entered is incorrect. Verify the syntax before reentering the command. 


BUTIL-6.10-8: The command completed, but one or more errors occurred. 


Explanation: An error occurred when you executed a command that performed a number of 
Btrieve operations. These commands include COPY, LOAD, or CLONE. This 
message is accompanied by additional messages that can help you identify the 
problem. 


BUTIL-6.10-9: The command did not complete due to an unrecoverable error. 


Explanation: The Maintenance utility returns this message when the command you entered 
did not complete successfully due to an unrecoverable error. Verify that the 
syntax you entered is correct before reentering the command. This message is 
accompanied by additional messages that can help you identify the problem. 


BUTIL-6.10-10: The command line contains a syntax error. 


Explanation: The Maintenance utility returns this message when the syntax of the command 
you entered is incorrect. Verify the syntax before reentering the command. 


BUTIL-6.10-11: The command line requires the index file. 


Explanation: If you specify the BUTIL -INDEX or -SAVE command (modified by the Y 
parameter) to the Btrieve Maintenance utility, you must specify the full 
pathname of an external index file. 


BUTIL-6.10-12: The command line requires the key number. 


Explanation: If you specify the DROP command or the SAVE command (modified by the 
N parameter) to the Btrieve Maintenance utility, you must specify the key 
number of the key you want to drop or by which you want to save the Btrieve 
file. 
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BUTIL-6.10-13: The key size for key of type xxxx is invalid. 


Explanation: The Maintenance utility returns this message when you specify an invalid key 
size for the key type. In a description file, the specified value of the Key 
Length element for a particular key is incorrect. Make sure that the value of 
each Key Length element is appropriate for the matching Key Type element. 


BUTIL-6.10-14: The key type is invalid. 


Explanation: The Maintenance utility returns this message when you specify an invalid key 
type. In a description file, the type specified for one of the keys is invalid. 
Make sure that all the Key Type elements in the file are assigned a valid type. 


BUTIL-6.10-15: The key segment descriptor value nn is invalid for a manual or null 
key. 
Explanation: The Maintenance utility returns this message when you specify an invalid 
value for the key segment descriptor. The value for the key segment descriptor 


can be any hexadecimal value from 00 to FF. An example of an invalid value 
is GL. 


BUTIL-6.10-16: BUTIL could not open the description file. 


Explanation: The Maintenance utility cannot open the description file. Before attempting to 
reenter the CREATE, INDEX, or SINDEX commands, make sure that the file 
exists and that you specify the correct full pathname. 


BUTIL-6.10-18: An error occurred during access of the sequential file. 


Explanation: The Maintenance utility returns this message when an error occurs during 
access of a sequential file. Check to see if the Btrieve source file is valid. 


BUTIL-6.10-19: BUTIL could not open the alternate collating sequence file. 


Explanation: The Maintenance utility cannot open the alternate collating sequence file that 
you specified in a description file. Make sure the Alternate Collating Sequence 
Filename element in the description file is assigned a valid pathname. 


BUTIL-6.10-20: An error occurred during access of the alternate collating sequence 
file. 


Explanation: An error occurred when the Maintenance utility accessed the alternate 
collating sequence file. Make sure the information in the alternate collating 
sequence file is formatted correctly. 


Status Codes andMessages 197 


BUTIL-6.10-21: The file version is earlier than 6.0. 


Explanation: The Maintenance utility returns this message when the RECOVER command 
cannot recover data from a Btrieve v5.x file, or the SALVAGE command 
cannot repair or salvage a Btrieve v5.x file. 


BUTIL-6.10-23: The /D parameter specified to the Requester was too small for BUTIL 
to receive the entire record. BUTIL is writing only nn bytes. 


Explanation: The Maintenance utility is writing only as many bytes as the value of the /D 
option allows. If you want the utility to write all the bytes in the record, specify 
a value for the /D option that is at least as large as the affected record. 


BUTIL-6.10-25: The /D parameter specified to BUTIL was too small for BUTIL to 
receive any part of the record. 


Explanation: The Maintenance utility returns this message when you specify an invalid 
value for the /D option. Return to the Setup utility and increase the value 
specified for the Largest Record Size configuration option. 


BUTIL-6.10-26: The data buffer is too small to hold any part of the record. 


Explanation: Btrieve cannot return any data in the data buffer because the data buffer is too 
small to hold it. Return to the Setup utility and increase the value specified for 
the Largest Record Size configuration option. 


BUTIL-6.10-27: An error occurred during the access of the variable page. BUTIL is 
writing the obtainable portion of the variable page. 


Explanation: The Maintenance utility returns this message when an error occurs during the 
recovery of a file with variable-length records. The file has been corrupted. 


BUTIL-6.10-30: The key position cannot exceed the record length. 


Explanation: The Maintenance utility returns this message when the range of the key 
position you specified is invalid. The key position you specify on a Btrieve 
call must be within the range of the record's length. For example, for a record 
that is 100 bytes long, a key position of 50 is within the correct range. 
However, a key position of 150 is not. 
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BUTIL-6.10-31: The key position plus key length cannot exceed the record length. 


Explanation: The Maintenance utility returns this message when the range of the key 
position you specified is invalid. The key position of a key plus its length 
cannot be larger than the record length. Verify that the key is defined so that 
its position plus its length does not exceed the record length. 


BUTIL-6.10-32: The key length must be an even number for key type xxxx. 


Explanation: The Maintenance utility returns this message when you specified an invalid 
key length for the key type. Some key types must contain an even number of 
bytes. Respecify the Key Length element correctly. 


BUTIL-6.10-36: The page size must be a multiple of 512, from 512 to 4,096. 


Explanation: The Maintenance utility returns this message if the page size you specified is 
not a multiple of 512, from 512 to 4,096. Specify an appropriate page size. 


BUTIL-6.10-37: The record length cannot exceed the page size. 


Explanation: The Maintenance utility returns this message if the record length you specified 
is invalid. In the description file, the record length you specified for the 
Record Length element is larger than the page size you specified for the Page 
Size element. Specify a record length that is smaller than the page size or 
increase the page size. 


BUTIL-6.10-38: The record length must be at least 4 and no greater than 4,096. 


Explanation: The Maintenance utility returns this message if the record length you specified 
is invalid. Specify a record length between 4 and 4,096 (inclusive) for Btrieve 
v5.x, or between 4 and 4,088 for Btrieve v6.x. 


BUTIL-6.10-41: The alternate collating sequence cannot be found. 


Explanation: The Maintenance utility cannot find the alternate collating sequence file you 
specified in the definition file. Verify that the alternate collating sequence file 
exists and that the name is correct in the definition file. 


BUTIL-6.10-43: The file exists, but the Replace option was not specified. 


Explanation: The Maintenance utility did not create a file when you specified the BUTIL - 
CREATE command because the file already exists. To recreate this file, 
specify the Replace Existing File element in the description file as y. 
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BUTIL-6.10-44: The file access error nn occurred for file xxxx. 


Explanation: The Maintenance utility returns the appropriate status code and filename for a 
file on which a file access error occurred during the beginning or end of 
continuous operation. The corrective measure depends on the status code 
received. Consult the screen message to get the value for nn, which 
corresponds to a numeric status code listed in this appendix. 


BUTIL-6.10-45: The number of duplicate keys must be between 1 and 119, 


Explanation: The number of duplicate keys you specified is invalid. Check the value 
specified for the Duplicate Key element in the description file. 


BUTIL-6.10-47: BUTIL cannot open the command file. 


Explanation: The Maintenance utility returns this message when it cannot open the 
specified command file. Make sure the command file exists and that you 
specified the command file location and filename correctly. 


BUTIL-6.10-48: The command file is empty. 


Explanation: The Maintenance utility returns this message 1f the command file you 
specified does not contain characters. Specify the desired commands in the 
command file before attempting to use the command file again. In addition, 
make sure you specified the correct command filename. 


BUTIL-6.10-49: The command file exceeds 1,000 bytes. 


Explanation: A command file cannot contain more than 1000 bytes. Verify that the 
command file adheres to this requirement. 


BUTIL-6.10-50: An internal error caused BUTIL to terminate. 


Explanation: The Maintenance utility detected an internal diagnostic error that caused it to 
terminate. 


BUTIL-6.10-52: Btrieve cannot be stopped when NetWare SQL is loaded. 


Explanation: The Maintenance utility returns this message when you attempt to unload 
Btrieve while NetWare SQL is loaded. Unload NetWare SQL before 
attempting to unload Btrieve again. 
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BUTIL-6.10-53: Btrieve error nn occurred for file or command xxxx. 


Explanation: The Maintenance utility returns a status code related to a particular file or 
command. The corrective measure depends on the status code received. 
Consult the screen message to get the value for nn, which corresponds to a 
numeric status code listed in this appendix. 


BUTIL-6.10-56: BUTIL is processing source file record nn. 


Explanation: This is an informational message from the Maintenance utility. No action is 
required. 


BUTIL-6.10-57: BUTIL has copied nn records so far. 


Explanation: The Maintenance utility copied the stated number of records since you issued 
the BUTIL -COPY command. After you receive this message, the command 
is still executing. 


BUTIL-6.10-58: BUTIL copied nn records. 


Explanation: The Maintenance utility copied the stated number of records after you issued 
the BUTIL -COPY command. This is the total number of records BUTIL 
copied while the command executed. 


BUTIL-6.10-59: BUTIL read nn records. 


Explanation: This is an informational message from the Maintenance utility. No action is 
required. When you issue a BUTIL -RECOVER command, the utility reads 
records in physical order from the specified file. When you issue a BUTIL - 
SAVE command, the utility reads records from the specified file using an 
index path. 


BUTIL-6.10-60: The end of the file occurred while BUTIL was expecting keyword xxxx 
on key segment descriptor nn. 


Explanation: | While the Maintenance utility was creating a file, it found a syntax error in the 
description file. Check the syntax of the description file. 


BUTIL-6.10-61: The end of the file occurred while BUTIL was expecting keyword xxxx. 


Explanation: | While the Maintenance utility was creating a file, it found a syntax error in the 
description file. Check the syntax of the description file. 
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BUTIL-6.10-62: BUTIL was expecting keyword xxxx on key segment descriptor nn. 


Explanation: | While the Maintenance utility was creating a file, it found a syntax error in the 
description file. Check the syntax of the description file. 


BUTIL-6.10-63: BUTIL was expecting keyword xxxx. 


Explanation: | While the Maintenance utility was creating a file, it found a syntax error in the 
description file. Check the syntax of the description file. 


BUTIL-6.10-64: nn records have been indexed. 


Explanation: This is an informational message from the utility. The utility displays the 
number of records that were indexed since you issued the BUTIL -INDEX 
command. No action is required. 


BUTIL-6.10-65: BUTIL has loaded no records. 


Explanation: The Maintenance utility did not load any records after you specified the 
BUTIL -LOAD command. Verify that you specified the command correctly 
and that the input file is in the correct format. 


BUTIL-6.10-66: BUTIL has loaded nn records so far. 


Explanation: The Maintenance utility loaded the stated number of records since you issued 
the BUTIL -LOAD command. When you receive this message, the command 
is still executing. 


BUTIL-6.10-67: BUTIL is processing sequential record nn. 


Explanation: This is an informational message from the Maintenance utility. No action is 
required. 


BUTIL-6.10-68: BUTIL has loaded nn records. 


Explanation: The Maintenance utility loaded the stated number of records after you issued 
the BUTIL -LOAD command. This is the total number of records BUTIL 
loaded while the command executed. 


BUTIL-6.10-69: BUTIL has read nn sequential records. 


Explanation: This is an informational message from the Maintenance utility. No action is 
required. 
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BUTIL-6.10-70: The Btrieve error nn occurred on closing a file. 


Explanation: The Maintenance utility returns this status code while closing a file. The 
corrective measure depends on the status code received. Consult the screen 
message to get the value for nn, which corresponds to a numeric status code 
listed in this appendix. 


BUTIL-6.10-71: BUTIL has recovered nn records so far. 


Explanation: The Maintenance utility recovered the stated number of records since you 
issued the BUTIL -RECOVER command. After you receive this message, the 
command is still executing. 


BUTIL-6.10-72: BUTIL has recovered nn records. 


Explanation: The Maintenance utility recovered the stated number of records after you 
issued the BUTIL -RECOVER command. This is the total number of records 
BUTIL recovered while the command executed. 


BUTIL-6.10-73: BUTIL is scanning the file. 


Explanation: The Maintenance utility is scanning a file while performing a BUTIL - 
SALVAGE command. No action is required. 


BUTIL-6.10-74: Btrieve error nn was returned for the Stop Command. 


Explanation: The Maintenance utility returns this status code after the BUTIL -STOP 
command was issued. The corrective measure depends on the status code 
received. Consult the screen message to get the value for nn, which 
corresponds to a numeric status code listed in this appendix. This message 
applies only to the DOS environment. 


BUTIL-6.10-76: When BUTIL wrote the Page Allocation Table at page #nn, an error 
occurred. 


Explanation: The Maintenance utility returns this message while salvaging a file if the file 
1s corrupted or when a hardware error occurs. 


BUTIL-6.10-77: When BUTIL wrote a mirror copy of the Page Allocation Table at page 
#nn, an error occurred. 


Explanation: The Maintenance utility returns this message while salvaging a file if the file 
is corrupted or when a hardware error occurs. 
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BUTIL-6.10-82: The file format is incorrect. 


Explanation: The Maintenance utility returns this message when the format for the file is 
prior to Btrieve v6.x. Check the format of the file. 


BUTIL-6.10-83: BUTIL is checking Page Allocation Table page #nn of #nn. 


Explanation: The Maintenance utility returns this message while performing a BUTIL - 
SALVAGE. No action is required. 


BUTIL-6.10-84: The Page Allocation Table entry nn on page nn at offset nn points to 
an invalid page. 


Explanation: The Maintenance utility returns this message when it encounters file 
corruption while performing a BUTIL -SALVAGE. You may lose some data. 
Check the salvaged file. 


BUTIL-6.10-86: The file's Page Allocation Table appears damaged. 


Explanation: The Maintenance utility returns this message while performing a BUTIL - 
SALVAGE. You may lose some data. Check the salvaged file. 


BUTIL-6.10-90: BUTIL could not allocate enough memory. 


Explanation: The Maintenance utility cannot continue with the BUTIL -SALVAGE 
command due to inadequate memory at the server. Free some memory at the 
server by unloading unused NLMs. 


BUTIL-6.10-91: BUTIL could not determine the size of the file. 


Explanation: The Maintenance utility cannot continue with the BUTIL -SALVAGE 
command. The file cannot be salvaged. Try to recover the file using the 
BUTIL -RECOVER command. 


BUTIL-6.10-92: The user terminated BUTIL. 
Explanation: The Maintenance utility returns this message to indicate that the user entered 
0 to quit when prompted by the utility. 
BUTIL-6.10-93: BUTIL has saved nn records so far. 


Explanation: The Maintenance utility saved the stated number of records since you issued 
the BUTIL -SAVE command. When you receive this message, the command 
is still executing. 
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BUTIL-6.10-94: BUTIL has saved nn records. 


Explanation: The Maintenance utility saved the stated number of records after you issued 
the BUTIL -SAVE command. This is the total number of records BUTIL 
saved while the command executed. 


BUTIL-6.10-128: The Btrieve Version is n.n. 


Explanation: The Maintenance utility returns the version of Btrieve that you are currently 
running. 


BUTIL-6.10-131: BUTIL was unable to create or open the sequential file. 


Explanation: The Maintenance utility returns this message when it is unable to create or 
open the specified file. Check the sequential file to make sure it exists and has 
the read-only attribute set. 


BUTIL-6.10-132: The disk volume is full. 


Explanation: The Maintenance utility returns this message when the disk volume is full. 
You must have more disk space to create or enlarge any Btrieve files. 


BUTIL-6.10-134: BUTIL was unable to create or open the new file. 


Explanation: The Maintenance utility returns this message when it is unable to create or 
open the specified file. Check the file specified for the BUTIL -SAVE, - 
SALVAGE, or -RECOVER command. The file may already exist. 


BUTIL-6.10-136: BUTIL was unable to write the new backup file. 


Explanation: The Maintenance utility returns this message when it is unable to write the 
new backup file. Verify that you specified the correct path and filename for the 
backup file. Also, make sure you have enough disk space for the file to be 
written. 


BUTIL-6.10-152: There was an error opening file xxxx. 


Explanation: | While performing the BUTIL -SALVAGE command, the Maintenance utility 
could not open the file. Check the Btrieve file attributes, path, and filename. 


BUTIL-6.10-155: BUTIL cannot open the Btrieve file xxxx. 


Explanation: The Maintenance utility returns this message when it cannot open the 
specified file. Check the path, filename, and file attributes. 
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Monitor Utility Messages 


The following messages are sent by the Btrieve Monitor utility 
(BTRMON.NLM). 


BTRMON-6.1-43: The utility cannot allocate memory sufficient for the operation. 


Explanation: Press Esc to continue. The Btrieve Monitor utility makes five attempts to 
allocate enough memory for the operation and, if unsuccessful, displays 
message 118. 


BTRMON-6.1-118: There is still insufficient memory for the operation. 


Explanation: The Btrieve Monitor utility displays this message when it has completed five 
unsuccessful attempts to allocate enough memory for the operation. You must 
either unload some NLMs, if possible, or wait for a time when server usage is 
less heavy. 


BTRMON-6.1-124: The utility cannot find the help file BTRMON.HLP. 


Explanation: The Btrieve Monitor utility displays this message when it cannot find the help 
file. Check your SYSTEM directory to make sure that the help file is present. 


BTRMON-6.1-128: This Btrieve file is no longer open. Please press the <Insert> key to 
update the file list. 


Explanation: The Btrieve Monitor utility displays this message when you select a file that 
was open when you began viewing active resources but is now closed. 


Rebuild Utility Messages 


The following messages are sent by the Rebuild utility (BREBUILD.NLM). 


BREBUILD-1.1-2: BREBUILD could not allocate memory. 


Explanation: The Rebuild utility displays this message when the server does not have 
adequate memory. Acquire more memory for the server. 


BREBUILD-1.1-3: BREBUILD could not rename xxxx to xxxx. 


Explanation: The Rebuild utility displays this message when the specified file does not 
exist. Check to see if the file exists. 
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BREBUILD-1.1-4: An incorrect Btrieve version is loaded. 


Explanation: The Rebuild utility displays this message when an incorrect Btrieve version is 
loaded. Unload the current version of Btrieve, and reload using Btrieve v6.x. 


BREBUILD-1.1-5: BREBUILD could not delete xxxx. 


Explanation: The Rebuild utility displays this message when it cannot delete the specified 
file. Check to see if the file is open. If it is open, close it. The Rebuild utility 
cannot delete a file while it is open. 


BREBUILD-1.1-6: An internal program error occurred. 


Explanation: The Rebuild utility detected an internal diagnostic error. 


BREBUILD-1.1-7: BREBUILD could not open xxxx. The Btrieve status was nn. 


Explanation: The Rebuild utility displays this message when it cannot open the specified 
file. Btrieve returns the specified status code. Consult the screen message to 
get the value for nn, which corresponds to a numeric status code listed in this 
appendix. 


BREBUILD-1.1-8: BREBUILD could not open xxxx in the accelerated mode. The 
Btrieve status code was nn. 


Explanation: The Rebuild utility displays this message when it cannot open the specified 
file in Accelerated mode. Consult the screen message to get the value for nn, 
which corresponds to a numeric status code listed in this appendix. 


BREBUILD-1.1-9: BREBUILD could not create the new file or files with the Btrieve 6.x 
advanced features. Ensure that the correct version of Btrieve is loaded with the 
Create Btrieve Files in Pre v6.x Format option set to No. 


Explanation: The Rebuild utility displays this message when it cannot create the new 
Btrieve files in v6.x format. Unload Btrieve by executing BSTOP, or unload 
Btrieve at the server console or at a workstation running RCONSOLE. 


BREBUILD-1.1-10: An invalid option was specified. 


Explanation: | Change the configuration options for the Rebuild utility through the Setup 
utility. Refer to “Installing and Configuring Btrieve” on page 43 for more 
information. When you run the Rebuild utility interactively, it checks the 
values you enter to ensure they are within the proper ranges. 
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BREBUILD-1.1-11 
dropped. 


Explanation: 


BREBUILD-1.1-12 


Explanation: 


BREBUILD-1.1-13 


Explanation: 


BREBUILD-1.1-14 


Explanation: 


BREBUILD-1.1-15 


Explanation: 


BREBUILD-1.1-16 


Explanation: 


BREBUILD-1.1-17 


Explanation: 


BREBUILD-1.1-18 


: Indexes are not consecutively numbered. Indexes will not be 


This is an informational message from the Rebuild utility. No action is 
required. 


: BREBUILD has copied nn records so far. 


This is an informational message from the Rebuild utility. No action is 
required. 


: BREBUILD is rebuilding nn key number nn. 


This is an informational message from the Rebuild utility. No action is 
required. 


: BREBUILD did not rebuild for the following reason: xxxx 


The Rebuild utility was not able to rebuild the file specified and returned this 
message. Eliminate the cause for this message and try to rebuild the file again. 


: Btrieve returned status nn for the following reason: xxxx 


Btrieve returned the specified status code. Consult the screen message to get 
the value for nn, which corresponds to a numeric status code listed in this 
appendix. 


: The xxxx file is already in 6.x format. 


The Rebuild utility displays this message when the specified file is already in 
Btrieve v6.x format. You do not need to rebuild the file. 


: The xxxx file is not a Btrieve file. 


The file you specified to rebuild is not a valid Btrieve file. The Rebuild utility 
cannot rebuild the file. 


: BREBUILD could not obtain the characteristics of the xxxx. The 


Btrieve status was nn. 


Explanation: 


The Rebuild utility returns the specified Btrieve status code. Consult the 
screen message to get the value for nn, which corresponds to a numeric status 
code listed in this appendix. 
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BREBUILD-1.1-19: 


Explanation: 


BREBUILD-1.1-20: 


Explanation: 


BREBUILD-1.1-21: 


Explanation: 


BREBUILD-1.1-22: 


Explanation: 


BREBUILD-1.1-23: 


Explanation: 


BREBUILD-1.1-24: 


Explanation: 


BREBUILD-1.1-25: 


Explanation: 


BREBUILD-1.1-26: 


Explanation: 


BREBUILD could not change to directory xxxx. 


The directory name you specified for the output directory is not valid. Specify 
a valid output directory name for the Rebuild utility on the command line or 
through the Setup utility. 


BREBUILD is processing xxxx. 


This is an informational message from the Rebuild utility. No action is 
required. 


BREBUILD is copying the xxxx to the temporary file xxxx. 


This is an informational message from the Rebuild utility. No action is 
required. 


The file was rebuilt successfully. 


This is an informational message from the Rebuild utility. No action is 
required. 


The utility could not open sys:\system\brebuild.log. 


The Rebuild utility displays this message if the file BREBUILD.LOG either 
does not exist or has been left open. 


An error occurred accessing xxxx. 


The Rebuild utility displays this message when you specify an invalid 
filename. Make sure you specified a valid filename. 


BREBUILD is setting the owner name of an empty target file. 


The Rebuild utility displays this message when an error occurs during the 
setting of an empty target file's owner name. You need to rerun the Rebuild 
utility. 


BREBUILD is dropping the indexes of an empty target file. 


The Rebuild utility displays this message when an error occurs during the 
dropping of an empty target file's indexes. You need to rerun the Rebuild 
utility. 
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BREBUILD-1.1-27: 


Explanation: 


BREBUILD-1.1-28: 


Explanation: 


BREBUILD-1.1-29: 


Explanation: 


BREBUILD-1.1-30: 


Explanation: 


BREBUILD-1.1-31: 


Explanation: 


BREBUILD-1.1-32: 


Explanation: 


BREBUILD-1.1-33: 


Explanation: 


BREBUILD-1.1-34: 


Explanation: 


BREBUILD is reading the first record from the old file. 


This is an informational message from the Rebuild utility. No action is 
required. 


BREBUILD is inserting records into the new file. 


This is an informational message from the Rebuild utility. No action is 
required. 


BREBUILD is reading records from the old file. 


This is an informational message from the Rebuild utility. No action is 
required. 


BREBUILD is putting back indexes on the new file. 


This is an informational message from the Rebuild utility. No action is 
required. 


BREBUILD could not create xxxx. The Btrieve status code was nn. 


The Rebuild utility displays this message when it cannot create the specified 
file. The utility returns the specified Btrieve status code. Consult the screen 
message to get the value for nn, which corresponds to a numeric status code 
listed in this appendix. 


BREBUILD copied a total of nn records. 


This is an informational message from the Rebuild utility. No action is 
required. 


BREBUILD start time is nn. 


This is an informational message from the Rebuild utility. No action is 
required. 


Key number nn is invalid. 


The Rebuild utility displays this message when the key specified for the Key 
Number (-K) option is invalid. Specify a valid key number for the Rebuild 
utility on the command line or through the Setup utility. 
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BREBUILD-1.1-35: 


Explanation: 


BREBUILD-1.1-36: 


Explanation: 


BREBUILD-1.1-37: 


Explanation: 


BREBUILD-1.1-38: 


Explanation: 


BREBUILD-1.1-39: 


Explanation: 


BREBUILD-1.1-40: 


Explanation: 


BREBUILD-1.1-42: 


Explanation: 


BREBUILD-1.1-44: 


Explanation: 


Page size nn is invalid. 


The Rebuild utility displays this message when the page size specified for the 
Page Size (-P) option is invalid. Specify a valid page size for the Rebuild 
utility on the command line or through the Setup utility. 


The page size will be changed to nn. 


This is an informational message from the Rebuild utility. No action is 
required. 


The rebuild process has ended. 


This is an informational message from the Rebuild utility. No action is 
required. 


BREBUILD was terminated by the user. 
The user entered Ctrl+C and the Rebuild utility was unloaded. 


BREBUILD was unloaded by the user. 


The user unloaded Btrieve and the Rebuild utility was unloaded. 


BREBUILD could not open the file xxxx. 


The Rebuild utility displays this message when it cannot open the specified 
file. The file may be open or may not exist. Check for one of these conditions. 


The specified local server xxxx is invalid. 


The Rebuild utility displays this message when the specified server name is 
not a local server. 


BREBUILD could not clone xxxx. The Btrieve status was nn. 


The Rebuild utility displays this message when it cannot clone the specified 
file. Btrieve returns the specified Btrieve status code. Consult the screen 
message to get the value for nn, which corresponds to a numeric status code 
listed in this appendix. 
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BREBUILD-1.1-45: The command line file xxxx does not have an <end> delimiter. 


Explanation: Each entry in the command file contains the utility options (if any) and the set 
of files to convert. Each entry must be followed by <end> or [end]. Edit the 
command file to include the necessary delimiter. 


BREBUILD-1.1-48: BREBUILD could not initialize the user interface library. 


Explanation: The Rebuild utility displays this message when the server has insufficient 
memory to initialize the user interface library. 


BREBUILD-1.1-63: BREBUILD could not initialize localized message table. 


Explanation: The Rebuild utility displays this message when the server has insufficient 
memory to initialize the localized message table. 


BREBUILD-1.1-64: BREBUILD is currently processing the following file: 


Explanation: This is an informational message from the Rebuild utility. No action is 
required. 


BREBUILD-1.1-66: BREBUILD could not open the xxxx. 


Explanation: The Rebuild utility displays this message when it cannot open the specified 
file. The file may be open or may not exist. Check for one of these conditions. 


Requester Utility Messages 


The following messages are sent by the Requester utility (BREQUTIL.NLM). 


BREQUTIL-6.1-3: The single-user version of Btrieve vn.n is loaded. 


Explanation: This is an informational message from the Requester utility. No action is 
required. 


BREQUTIL-6.1-4: The network version of Btrieve vn.n is loaded. 


Explanation: This is an informational message from the Requester utility. No action is 
required. 


212 Birieve Installation and Operation 


BREQUTIL-6.1-5: The multi-user version of Btrieve vn.n is loaded. 


Explanation: This is an informational message from the Requester utility. No action is 
required. 


BREQUTIL-6.1-6: The OS/2 DynaLink for Btrieve vn.n is loaded. 


Explanation: This is an informational message from the Requester utility. No action is 
required. 


BREQUTIL-6.1-7: Btrieve version vn.n is loaded. 


Explanation: This is an informational message from the Requester utility. No action is 
required. 


BREQUTIL-6.1-8: Btrieve is not loaded. 


Explanation: Either the Btrieve Requester (BREQUEST.EXE) or Record Manager 
(BTRIEVE.EXE) is not loaded. 


BREQUTIL-6.1-9: Btrieve operation xx was unsuccessful. The number of the 
applicable Btrieve status code is nn. 


Explanation: The Requester utility returns the specified Btrieve status code. Consult the 
screen message to get the value for nn, which corresponds to a numeric status 
code listed in this appendix. For information about the Btrieve operation xx, 
see Chapter 4, "Btrieve Operations," in the Btrieve Programmer's Manual. 


BREQUTIL-6.1-16: Btrieve cannot be removed from memory while NetWare SQL is 
loaded. 


Explanation: This is an informational message from the Requester utility. No action is 
required. 
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Roll Forward Utility for DOS 


BROLLFWD-6.1-1: 
operation. 


Explanation: 


BROLLFWD-6.1-2: 


Explanation: 


BROLLFWD-6.1-3: 


Explanation: 


BROLLFWD-6.1-4: 
name: 


Explanation: 


This section lists and describes the messages that the Roll Forward utility for 
the DOS environment can send. 


This workstation has insufficient memory to complete the 


The workstation does not have enough memory for the DOS Roll Forward 
utility to complete the current operation. Free some memory on the 
workstation and restart the Roll Forward process. 


The log file was created at nn:nn. 


This is an informational message from the DOS Roll Forward utility. No 
action is required. 


An internal program error has occurred. 


The DOS Roll Forward utility detected an internal program error. 


The specified owner name is invalid. Please reenter the owner 


The DOS Roll Forward utility returns this message when the specified owner 
name is invalid. Specify a valid owner name and start the roll forward process 
again. The maximum length for an owner name is 8 bytes. Enter a valid owner 
name. 


BROLLFWD-6.1-21: The utility is unable to open xxxx. The number of the applicable 
system error code is nn. 


Explanation: 


The DOS Roll Forward utility returns this message when it cannot open the 
specified file. The file may be open or may not exist. 


BROLLFWD-6.1-22: An error occurred while the utility was reading xxxx. 


Explanation: 


The DOS Roll Forward utility returns this message when it cannot read the 
specified file. Verify that the file exists. If the file exists, ensure that the file is 
closed. 
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BROLLFWD-6.1-23: File xxxx ended unexpectedly during the roll forward process. 


Explanation: The DOS Roll Forward utility returns this message when the specified file 
ended unexpectedly during the roll forward process. The associated log file is 
corrupt. You cannot use this log file. 


BROLLFWD-6.1-24: The utility could not find the log file header information in xxxx. 


Explanation: The DOS Roll Forward utility returns this message when no log file header 
information was found for the specified file. The associated log file is corrupt. 
You cannot use this log file. 


BROLLFWD-6.1-25: The xxxx file contains incorrect syntax in the log file header. 


Explanation: The DOS Roll Forward utility returns this message when the log file header 
for the specified file contains incorrect syntax. The associated log file is 
corrupt. You cannot use this log file. 


BROLLFWD-6.1-26: Btrieve operation xx was unsuccessful. The number of the 
applicable Btrieve status code is nn. 


Explanation: Btrieve returns the specified Btrieve operation and status codes to the DOS 
Roll Forward utility. The specified Btrieve operation was unsuccessful. 
Consult the screen message to get the value for nn, which corresponds to a 
numeric status code listed in this appendix. For more information about the 
Btrieve operation xx, refer to the Btrieve Programmer's Manual. 


BROLLFWD-6.1-27: The utility could not find xxxx in the BLOG.CFG file. 


Explanation: The DOS Roll Forward utility returns this message when the specified file is 
not found in the log configuration file, BLOG.CFG. Edit the BLOG.CFG file 
to add the filename specified. For more information about the BLOG.CFG 
file, refer to the section “Creating the Log Configuration File” on page 123. 


BROLLFWD-6.1-28: The record size of the Btrieve file file xxxx exceeds the size of the 
data buffer specified with the /d parameter. 


Explanation: The DOS Roll Forward utility returns this message when the value specified 
for the /D option is invalid. Increase the value for the /D option. 
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BROLLFWD-6.1-29: The length of the data to be printed, specified with the /t option, 
is invalid. Valid data lengths range from 1 through the value of the data buffer size 
specified with the /d option. 


Explanation: The DOS Roll Forward utility returns this message when the value specified 
for the /T option is invalid. Change the value for this option. 


BROLLFWD-6.1-30: The length of the key to be printed, specified with the /k option, 


is invalid. Valid lengths for printing keys range from 1 through 255 characters. 


Explanation: The DOS Roll Forward utility returns this message when the value specified 
for the /K option is invalid. Enter a value in the range | through 255. 


BROLLFWD-6.1-31: 0/1 entry in the log file has been processed. 


Explanation: This is an informational message from the DOS Roll Forward utility. No 
action is required. 


BROLLFWD-6.1-32: xx in the log file have been processed. 


Explanation: This is an informational message from the DOS Roll Forward utility. No 
action is required. 


BROLLFWD-6.1-42: The disk is full. 


Explanation: The disk is full. Free some space on the disk and run the DOS Roll Forward 
utility again. 


BROLLFWD-6.1-43: The utility started the roll forward process at nn:nn. 


Explanation: This is an informational message from the DOS Roll Forward utility. No 
action is required. 
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Roll Forward Utility for OS/2 


This section lists and describes the messages that the Roll Forward utility for 
the OS/2 environment can send. 


PBROLL-6.10-1: Window creation failed. 


Explanation: The underlying cause of this condition is insufficient free memory. To 
complete the operation, you must free some of the memory currently allocated 
or terminate some of the active applications. 


PBROLL-6.10-2: Window positioning failed. 


Explanation: The OS/2 Roll Forward utility returns this message when memory has been 
corrupted. Try turning your computer off and on to reinitialize the memory. 


PBROLL-6.10-3: Cannot open the following file: filename. 


Explanation: The OS/2 Roll Forward utility cannot open the specified file (Btrieve file, log 
file, or listing file). Make sure that the specified file exists and then specify the 
correct, full pathname. 


PBROLL-6.10-4: An error occurred during input or output for the following file: 
filename. 


Explanation: Btrieve either cannot read from or cannot write to the disk. Make sure that the 
file attributes are set correctly. You may also try running server diagnostics or 
checking the disk subsystem. 


PBROLL-6.10-5: The following file ended unexpectedly: filename. 


Explanation: The OS/2 Roll Forward utility returns this message when the log file for the 
specified Btrieve file is corrupt. You cannot use this log file. 


PBROLL-6.10-6: There is no header information in the following file: filename. 


Explanation: The OS/2 Roll Forward utility cannot find the log file header information in 
the specified log file because the log file is corrupt. You cannot use this log 
file. 
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PBROLL-6.10-7: There is incorrect header syntax in the following file: filename. 


Explanation: The OS/2 Roll Forward utility returns this message when the specified log file 
is corrupt and contains incorrect syntax in the log file header. You cannot use 
this log file. 


PBROLL-6.10-8: The following file was not found in BLOG.CFG: filename. 


Explanation: The OS/2 Roll Forward utility returns this message when it cannot find the 
specified file in the log configuration file. Edit the BLOG.CFG file to add the 
filename specified. For more information about the BLOG.CFG file, refer to 
the section “Creating the Log Configuration File” on page 123. 


PBROLL-6.10-9: The length of the record exceeds the current data buffer size for the 
following file: filename. 


Explanation: The record size of the specified Btrieve file exceeds the data length you 
specified in the Options dialog box. Change the data length accordingly. 


PBROLL-6.10-10: Btrieve error: Operation: xx Status Code: nn 


Explanation: Btrieve returns the specified Btrieve operation and status codes to the OS/2 
Roll Forward utility. The specified Btrieve operation was unsuccessful. 
Consult the screen message to get the value of Status Code nn, which 
corresponds to a numeric status code listed in this appendix. For more 
information about the Btrieve operation xx, refer to the Btrieve Programmer's 
Manual. 


PBROLL-6.10-11: The following unknown error occurred: nn. 


Explanation: The OS/2 Roll Forward utility detected an internal diagnostic error. 


PBROLL-6.10-12: There was an invalid owner name. 


Explanation: The OS/2 Roll Forward utility returns this message when the specified owner 
name is invalid. Specify a valid owner name and start the roll forward process 
again. The maximum length for an owner name is 8 bytes. Enter a valid name 
in the Owner text box. 


PBROLL-6.10-13: Unable to add the item to the queue. 


Explanation: The OS/2 Roll Forward utility works on a queued-job basis. The maximum 
number of files allowed in the queue is 32. That is, the utility cannot roll 
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forward more than 32 files at one time. If you want to roll forward all the files 
on a specified volume, edit the log configuration file, BLOG.CFG, as needed 
to ensure that no more than 32 files are specified. If you want to roll forward 
individual files, make sure that you do not specify more than 32 files at one 
time. 


PBROLL-6.10-14: There is not enough memory available. 


Explanation: The workstation does not have enough memory for the OS/2 Roll Forward 
utility to complete the current operation. Free some memory on the 
workstation and restart the roll forward process. 


PBROLL-6.10-15: The data length value is invalid. It must be between 1 and 64. 


Explanation: The OS/2 Roll Forward utility returns this message when the specified data 
length is invalid. The Data Length option in the Options dialog box specifies 
the number of kilobytes allocated for the data buffer that the utility uses to 
process the logged entries. The value specified for the Data Length option 
should be at least as large as the largest record to be rolled forward. Specify an 
appropriate value for the Data Length option in the Options dialog box. 


PBROLL-6.10-16: Could not allocate the data buffer. 


Explanation: The OS/2 Roll Forward utility returns this message when the system is low on 
memory. Free some system memory or specify a smaller data buffer, and run 
the utility again. 


PBROLL-6.10-17: Could not open the list file. 


Explanation: The OS/2 Roll Forward utility returns this message when the pathname you 
entered for the new list file (when the disk ran out of space) is invalid. Specify 
a valid pathname for the new list file. 


PBROLL-6.10-18: ABORT—The data files may be left in an inconsistent state. Please 
confirm abort. 


Explanation: The OS/2 Roll Forward utility returns this message when you select the Abort 
option during the roll forward process. Selecting Abort prevents the utility 
from applying the rest of the logged operations to the backup copy of the 
corresponding Btrieve file. Confirming the abort can leave the Btrieve file that 
is currently being rolled forward in an inconsistent state (that is, only partially 
updated). Select Yes to confirm you want to abort or No to cancel the abort 
and continue the roll forward process. 
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PBROLL-6.10-19: This utility could not open NOVDB.INI. 


Explanation: The OS/2 Roll Forward utility returns this message when it cannot open the 
initialization file, NOVDB.INI. Check the file attributes of the NOVDB.INI 
file to ensure that you have access rights to it. This file should be in the 
directory you selected when choosing the options for the utility. 


PBROLL-6.10-20: This item or volume is already in the queue. 


Explanation: The OS/2 Roll Forward utility returns this message when the item or volume 
you entered in the queue has already been entered. Enter a different item or 
volume. 


PBROLL-6.10-21: The listing length exceeds the buffer length. 


Explanation: The OS/2 Roll Forward utility returns this message when the specified listing 
length is invalid. In the Options dialog box, the Data to List option exceeds the 
value you entered for the Data Length option. The Data to List option specifies 
the length of the data buffer that will be printed in the list file for each 
operation that is rolled forward. The Data Length option specifies the number 
of kilobytes allocated for the data buffer that the utility uses to process the 
logged entries. Make sure the value you enter for the Data to List option does 
not exceed the value you entered for the Data Length option. 


PBROLL-6.10-22: The listing length is invalid. 


Explanation: The OS/2 Roll Forward utility returns this message when the specified listing 
length is invalid. You entered an invalid value for the Data to List or the Key 
to List option in the Options dialog box. The Data to List option specifies the 
length of the data buffer that will be printed in the list file for each operation 
that is rolled forward. Similarly, the Key to List option specifies the length of 
the key buffer that will be printed in the list file for each operation that is rolled 
forward. In the options dialog box, make sure the value you enter for the Data 
to List option does not exceed the value you entered for the Data Length 
option and the Key to List option does not exceed 255 bytes. 


PBROLL-6.10-23: The key listing length cannot exceed 255. 


Explanation: The OS/2 Roll Forward utility returns this message when the specified key 
listing length is invalid. The value you entered for the Key to List option in the 
Options dialog box exceeds 255 bytes. The Key to List option specifies the 
length of the key buffer that will be printed in the list file for each operation 
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that is rolled forward. Make sure the value you enter for the Key to List option 
does not exceed 255 bytes. 


PBROLL-6.10-24: Only one instance is allowed to run. 
Explanation: You tried to run the OS/2 Roll Forward utility, but it is already running. 


Roll Forward Utility for Windows 


This section lists and describes the messages that the Roll Forward utility for 
the Windows environment can send. 


WBROLL-6.1-1: Could not open configuration file BLOG.CFG. 


Explanation: The Windows Roll Forward utility cannot open the log configuration file, 
BLOG.CFG. Make sure that the file is in the system directory 
SYSASYSTEM. For more information about the BLOG.CFG file, refer to the 
section “Creating the Log Configuration File” on page 123. 


WBROLL-6.1-2: Continue roll forward? 


Explanation: The Windows Roll Forward utility returns this message when one of the files 
cannot be rolled forward. You can continue rolling forward the other files, or 
you can stop the roll forward process. Select Yes to continue or No to stop. 
Stopping the roll forward process prevents the Roll Forward utility from 
applying the rest of the logged operations to the backup copy of the 
corresponding Btrieve file. This can leave your Btrieve files in an inconsistent 
state (that is, only partially updated). 


WBROLL-6.1-3: Cannot open the following file: filename. 


Explanation: The Windows Roll Forward utility cannot open the specified file (Btrieve file, 
log file, or listing file). Make sure that the specified file exists and then specify 
the correct, full pathname. 


WBROLL-6.1-4: An error occurred during input or output for the following file: 
filename. 


Explanation: Btrieve either cannot read from or cannot write to the disk. Make sure that the 
file attributes are set correctly. You may also try running server diagnostics. 
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WBROLL-6.1-5: The following file ended unexpectedly: filename. 


Explanation: The Windows Roll Forward utility returns this message when the log file for 
the specified Btrieve file is corrupt. You cannot use this log file. 


WBROLL-6.1-6: There is no header information in the following file: filename. 


Explanation: The Windows Roll Forward utility cannot find the log file header information 
in the specified log file because the log file is corrupt. You cannot use this log 
file. 


WBROLL-6.1-7: There is incorrect header syntax in the following file: filename. 


Explanation: The Windows Roll Forward utility returns this message when the specified log 
file is corrupt and contains incorrect syntax in the log file header. You cannot 
use this log file. 


WBROLL-6.1-8: The following file was not found in BLOG.CFG: filename. 


Explanation: The Windows Roll Forward utility returns this message when the specified file 
1s not found in the log configuration file, BLOG.CFG. Edit the BLOG.CFG 
file to add the filename specified. For more information about the BLOG.CFG 
file, refer to the section “Creating the Log Configuration File” on page 123. 


WBROLL-6.1-9: The length of the record exceeds the current data buffer size for the 
following file: filename. 


Explanation: The Windows Roll Forward utility returns this message when the specified 
record length is invalid. The record size of the specified Btrieve file exceeds 
the data length you specified in the Options dialog box. Change the data length 
accordingly. 


WBROLL-6.1-10: Btrieve error: Operation: xx Status Code: nn 


Explanation: Btrieve returns the specified Btrieve operation and status codes to the 
Windows Roll Forward utility. The specified Btrieve operation was 
unsuccessful. Consult the screen message to get the value of Status Code nn, 
which corresponds to a numeric status code listed this appendix. For more 
information about the Btrieve operation xx, refer to the Btrieve Programmer's 
Manual. 
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WBROLL-6.1-11 


Explanation: 


WBROLL-6.1-12 


Explanation: 


WBROLL-6.1-13 


Explanation: 


WBROLL-6.1-14 


Explanation: 


WBROLL-6.1-15 


Explanation: 


WBROLL-6.1-16 


Explanation: 


: The following unknown error occurred: nn. 


The Windows Roll Forward utility detected an internal diagnostic error. 


: There was an invalid owner name. 


The Windows Roll Forward utility returns this message when the specified 
owner name is invalid. Specify a valid owner name and start the roll forward 
process again. The maximum length for an owner name is 8 bytes. Enter a 
valid name in the Owner text box. 


: The utility was unable to add the item to queue. 


The Windows Roll Forward utility works on a queued-job basis. The 
maximum number of files allowed in the queue is 32. That is, the utility cannot 
roll forward more than 32 files at one time. If you want to roll forward all the 
files on a specified volume, edit the log configuration file, BLOG.CFG, as 
needed to ensure that no more than 32 files are specified. If you want to roll 
forward individual files, make sure that you do not specify more than 32 files 
at one time. 


: There is not enough memory available. 


The workstation does not have enough memory for the Windows Roll 
Forward utility to complete the current operation. Free some memory on the 
workstation and restart the roll forward process. 


: The data length value is invalid. It must be between 1 and 64. 


The Windows Roll Forward utility returns this message when the specified 
data length is invalid. The Data Length option in the Options dialog box 
specifies the number of kilobytes allocated for the data buffer that the utility 
uses to process the logged entries. The value specified for the Data Length 
option should be at least as large as the largest record to be rolled forward. 
Specify an appropriate value for the Data Length option in the Options dialog 
box. 


: Could not allocate the data buffer. 


The Windows Roll Forward utility returns this message when the system is 
low on memory. Free some system memory or specify a smaller data buffer, 
and run the utility again. 
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WBROLL-6.1-17: Could not open the list file. 


Explanation: The Windows Roll Forward utility returns this message when the pathname 
you entered for the new list file (when the disk ran out of space) is invalid. 
Specify a valid pathname for the new list file. 


WBROLL-6.1-18: ABORT — The data files may be left in an inconsistent state. Please 
confirm abort. 


Explanation: The Windows Roll Forward utility returns this message when you select the 
Abort option during the roll forward process. Selecting Abort prevents the 
Roll Forward utility from applying the rest of the logged operations to the 
backup copy of the corresponding Btrieve file. Confirming the abort can leave 
the Btrieve file that is currently being rolled forward in an inconsistent state 
(that is, only partially updated). Select Yes to confirm you want to abort or No 
to cancel the abort and continue the roll forward process. 


WBROLL-6.1-19: Log file name too long. Max = 120. 


Explanation: The Windows Roll Forward utility returns this message when the length of the 
log filename you specified is greater than 120 bytes. Specify an appropriate 
length for the log file. 


WBROLL-6.1-20: This item or volume is already in the queue. 


Explanation: The Windows Roll Forward utility returns this message when the item or 
volume you entered in the queue has already been entered. Enter a different 
item or volume. 


WBROLL-6.1-21: The listing length exceeds the buffer length. 


Explanation: The Windows Roll Forward utility returns this message when the specified 
listing length is invalid. In the Options dialog box, the Data to List option 
exceeds the value you entered for the Data Length option. The Data to List 
option specifies the length of the data buffer that will be printed in the list file 
for each operation that is rolled forward. The Data Length option specifies the 
number of kilobytes allocated for the data buffer that the utility uses to process 
the logged entries. Make sure the value you enter for the Data to List option 
does not exceed the value you entered for the Data Length option. 
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WBROLL-6.1-22: Pathname is too long. 


Explanation: The Windows Roll Forward utility returns this message when the pathname 
you specified is greater than 240 bytes. Specify a shorter pathname. 


WBROLL-6.1-24: Only one instance is allowed to run. 


Explanation: You tried to run the Windows Roll Forward utility, but it is already running. 


Setup Utility Messages 


The following messages are sent by the Setup utility (BSETUP.NLM). 


BSETUP-6.1-40: The Btrieve Setup utility was unable to save the file. 


Explanation: The Setup utility was not able to save the Btrieve configuration options to the 
BSTART.NCF file. Retry the operation. 


BSETUP-6.1-43: The attempted memory allocation failed. 


Explanation: The Setup utility cannot allocate enough internal memory to display the 
Rebuild log file. 


BSETUP-6.1-63: The BSTART.NCF file is incomplete or invalid. 


Explanation: The Setup utility is unable to save the configuration option changes to 
BSTART.NCF because the file is incomplete or invalid. You may want to 
delete BSTART.NCF and recreate it in the Setup utility. 


BSETUP-6.1-73: The Btrieve Setup utility could not find the BSTART.NCF file, which 
must reside in the SYS:SYSTEM directory on the server. 


Explanation: The Setup utility cannot find the BSTART.NCF file. IF BSTART.NCF does not 
exist, you must create it through the Setup utility. 


BSETUP-6.1-75: To implement the configuration changes, first unload 
BSPXCOM.NLM and BTRIEVE.NLM, and then use the BSTART.NCF file to reload 
BSPXCOM.NLM and BTRIEVE.NLM. 


Explanation: For the changes you made to the configuration options to take effect, you must 
unload BSPXCOM.NLM and BTRIEVE.NLM and then reload them using 
BSTART.NCF. 
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BSETUP-6.1-100: The BSTART.NCF file was created with the default configuration 
settings. To view or change these settings, select the Set Btrieve Configuration 
option on the Available Options menu. 


Explanation: Select the stated option within the Setup utility to change the configuration 
options for Btrieve in the BSTART.NCF file. 


BSETUP-6.1-121: WARNING: Before running the Btrieve Rebuild utility, be sure to 
back up all your Btrieve data files. 


Explanation: Before running the Rebuild utility, make sure you have backed up all your 
Btrieve data files. Having a backup copy ensures against data loss if a power 
interruption occurs while you are running the utility. Another reason it is better 
to keep a backup is that the Rebuild utility deletes the original Btrieve files. 


BSETUP-6.1-122: You must specify the Rebuild Configuration parameters before you 
can execute the Rebuild utility. 


Explanation: Before you canrun the Rebuild utility, you must specify appropriate values for 
the Rebuild configuration options in the Setup utility. Please do so before 
attempting to run the Rebuild utility again. 


BSETUP-6.1-131: The Output Directory pathname does not require a file 
specification. 


Explanation: Do not specify a filename as part of the output directory path. 


BSETUP-6.1-132: Before rebuilding Btrieve files on a remote server, make sure the 
following files are loaded: BROUTER.NLM and BTRIEVE.NLM on the local server, and 
BSPXCOM.NLM and BTRIEVE.NLM on the remote server. 


Explanation: The NLMs listed in the message must be loaded on a local server and a remote 
server before attempting to rebuild files on a remote server. 


BSETUP-6.1-148: The Btrieve Setup utility could not find the file BREBUILD.NLM in 
the system directory, so you cannot invoke the Rebuild utility at this time. 


Explanation: The Setup utility returns this message when it cannot find the file 
BREBUILD.NLM. The file BREBUILD.NLM must be in the system 
directory. Please verify that it is in the correct directory. 
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BSETUP-6.1-152: Either the Input Directory pathname is invalid, or no matching files 
could be found. Please check the pathname. 


Explanation: The Setup utility returns this message when the path specified for the Files To 
Be Converted field is invalid or when no files exist in the directory specified. 


BSETUP-6.1-153: Either the Output Directory pathname is invalid, or no matching 
files could be found. Please check the pathname. 


Explanation: The Setup utility returns this message when the path specified for the Output 
Directory field does not exist on the local server. 


BSETUP-6.1-158: The Btrieve Setup utility could not create a screen for the Rebuild 
utility, so you cannot invoke the Rebuild utility at this time. 


Explanation: The Setup utility cannot invoke the Rebuild utility because too many screens 
are active at this time. Try the Rebuild utility again later when there is less 
activity on the server. 


BSETUP-6.1-159: The Btrieve Setup utility could not open the Rebuild error log file. 


Explanation: | When you attempted to view the Rebuild log file, the Setup utility was not able 
to open the log file. Verify that the file exists before retrying the operation. 


BSETUP-6.1-160: The attempt to read the Rebuild error log file failed. 


Explanation: The Setup utility was not able to read the Rebuild log file when you attempted 
to view it. Check to see that the log file exists. 


BSETUP-6.1-162: The Rebuild utility cannot be loaded because the BTRIEVE.NLM is 
not loaded. Please load Btrieve using the BSTART.NCF file. 


Explanation: Btrieve must be loaded before you run the Rebuild utility. Load 
BTRIEVE.NLM using BSTART.NCF. 


BSETUP-6.1-166: The utility found no files in the specified directory path. Please 
check the pathname. 


Explanation: The Setup utility cannot find any Btrieve files to rebuild in the chosen 
directory (specified for Files To Be Converted). Verify that you specified the 
correct directory. 
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BSETUP-6.1-167: The Rebuild utility could not be invoked at this time. 


Explanation: The Setup utility returns this message when it cannot invoke the Rebuild 
utility. Check to make sure that the version 1.1 of BREBUILD.NLM is loaded 
at the server. If it is not, load it at this time. 


BSETUP-6.1-168: The Btrieve Setup utility could not create the semaphore which 
synchronizes BSETUP.NLM and BREBUILD.NLM, so you cannot invoke the Rebuild 
utility at this time. 


Explanation: The semaphore used to synchronize the Setup utility and the Rebuild utility 
could not be created. Try the utility at a later time when there is less activity 
at the file server or use the command line version of BREBUILD. 


228 Btrieve Installation and Operation 


Glossary 


alternate collating sequence 
A sorting sequence other than the standard ASCII sequence that specifies the 
order in which Btrieve sorts keys. 


application 
A program or set of programs, such as a spreadsheet or a payroll application, 
that performs a task or a group of related tasks. Also, a program written by or 
for a user to apply to the user's work. 


application interface 
A program that allows access to Btrieve files from an application program. 


ascending 
A key attribute that instructs Btrieve to collate an index in ascending order. 
ASCII 
An acronym for American Standard Code for Information Interchange. ASCII 
is a 7-bit information code that defines 128 standard characters, including 
control characters, letters, numbers, and symbols. 
Btrieve 


A key-indexed record manager for file handling. A function call from a 
standard programming language or from NetWare SQL invokes Btrieve. 


Btrieve Requester 
The Btrieve Requester program for the applicable DOS, OS/2, Windows, or 
UnixWare environment. The program resides at a workstation and provides 
communication between Btrieve and a workstation application making 
Btrieve calls. 
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buffer 
A storage area in memory that is used to store data temporarily. 


cache 
The area of memory in which Btrieve stores images of physical disk pages. 
Btrieve uses the cache to reduce the number of physical disk I/O requests. 


case insensitive 
A key characteristic that instructs Btrieve to sort an index so that values in 
uppercase letters are sorted in the same order as values in lowercase letters. 
(For example, SANDY is equal to sandy.) 


chunk 
Any arbitrary portion of a record, specified by its offset and length. Btrieve 
v6.1 allows applications to update and retrieve portions of very large records, 
called chunks, rather than the entire record. 


command file 
A user-defined file that contains a sequence of commands. 


concurrency controls 
The methods Btrieve uses to resolve possible conflicts when two applications 
attempt to access the same data. Controls include passive control, record 
locking, and transaction control. 


configuration 
The customization of a program such as Btrieve. You can customize Btrieve 
through the Setup utility. 


configuration options 
Specifications defined for Btrieve when it is loaded. Configuration options 
control the way in which Btrieve operates. You can use the Setup utility to 
change the configuration options. 


connection number 


The unique identifier number that NetWare assigns when a workstation 
attaches to a server. 
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continuous operation 


database 


default 


description file 


directory 


DOS 


duplicatable 


A Btrieve feature that allows you to back up data files while they are open and 
in use. Btrieve opens the files in read-only mode to allow backup utilities to 
access the files' static images. Btrieve stores changes to the original files in 
temporary files called delta files. When the backup is complete, Btrieve 
automatically updates the original files with the changes stored in the delta 
files. Btrieve deletes each temporary file as soon as all applications close the 
Btrieve data file corresponding to that delta file. 


A set of one or more records or files that contain information on a related 
subject. 


A preset option or value. For example, the default directory or disk drive is the 
one in which you are currently working. 


An ASCII file containing information that the Maintenance utility commands 
CREATE, INDEX, and SINDEX need to perform their operations. 


A disk structure that contains files. A directory may also contain 
subdirectories. 


The DR DOS, MS-DOS, or PC-DOS operating system. 


A key attribute specifying that multiple records in a file can have the same 
value in the key field. 


dynamic link library (DLL) 


A program library that contains related modules of compiled code. At runtime, 
the application reads the functions in the DLL. This process is called dynamic 
linking. 


dynamic link routine 


field 


In OS/2 and Windows v3.x, a program that the operating system loads on 
demand (dynamically) and terminates automatically. 


The smallest meaningful unit of data in a file. 
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file 


index 


index balancing 


integrity control 


key 


manual key 


modifiable 


A collection ofrecords stored on a disk. A file is sometimes also referred to as 
a physical file. 


A key or a group of keys that Btrieve uses to sort a file. See also “key” on page 
232. 


The process of searching for available space in sibling index pages when a 
given index page becomes full, and then rotating values from the full page into 
the pages that have space available. Index balancing is a new feature you can 
activate in Btrieve v6.1 (as explained in “Installing and Configuring Btrieve” 
on page 43). 


A method of ensuring that data in a file is complete and accurate. Btrieve uses 
concurrency controls and shadow paging to guarantee data file integrity. See 
also “concurrency controls” on page 230 and “shadow paging” on page 234. 


A field in a Btrieve file by which the file can be sorted. See also “index” on 
page 232. 


A modified form of the null key, useful in excluding particular records from 
the index. In a manual key, if every byte of one segment contains the null 
value, Btrieve excludes the key from the index. (The Btrieve Programmer's 
Manual refers to manual keys as "any-segment null keys.") 


A key attribute that allows you to modify the key field during an update to a 
file. Ifa key is not modifiable, you cannot change the value in the key field. 


NetWare Loadable Module (NLM) 


NetWare SQL 


A server program built into server memory with NetWare. You can load or 
unload an NLM while the server is running. The NLM becomes part of the 
operating system and can access NetWare directly. 


Novell's relational data access system, which resides at the server as an NLM. 
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null key 


owner name 


page 


pathname 


pre-imaging 


record locking 


Record Manager 


A key field that can be a user-defined character. For null keys, Btrieve does 
not include the record in the index if the record's key value matches the null 
value. (The Btrieve Programmer's Manual refers to null keys as "all-segment 
null keys.") 


A password that protects data files from unauthorized access by Btrieve 
applications. You can assign an owner name using the Maintenance utility or 
by implementing a Set Owner record operation. 


A unit of a data file. A page is the smallest unit of storage that Btrieve moves 
between main memory and disk. Pages contain a multiple of 512 bytes (up to 
4,096 bytes). 


The server name, volume, directory path, and filename that uniquely identify 
a file. 


Storing the image of a file page before updating a record on the page. Btrieve 
v5.x and earlier use pre-imaging to provide recovery capabilities in case a file 
is damaged or a system failure occurs during an update to the file. 


A type of concurrency control that enables an application to lock the record it 
is accessing within a file. Other users can read the record, but no other user 
can lock, update, or delete the record until the application that holds the lock 
releases it. 


The server-based Btrieve Record Manager is a program that resides at the 
server and handles data I/O with the file system. The client-based Btrieve 
Record Manager resides at the workstation and handles data I/O with the file 
system through operating system calls. 


referential integrity (Rl) 


The assurance that when a field in one table references a field in another table, 
changes to these fields are synchronized. 
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Requester 
A program that resides at a workstation and passes requests from an 
application to a server-based application. 


roll back 
Aborting a transaction and undoing all the changes made to a file during the 
transaction, thus restoring the file to the state it was in before the transaction 
began. See also “transaction” on page 235. 


roll forward 
Recovering changes made to a Btrieve file between the time logging is 
initiated and a system failure. See also “roll back” on page 234 and “roll in” 
on page 234. 


roll in 
Writing to a Btrieve original file all the changes made to the corresponding 
temporary file during the continuous operation backup period. When the 
backup is complete, Btrieve automatically updates the original file with the 
changes and deletes the temporary file. See also “continuous operation” on 
page 231. 


segmented 
A key attribute that allows a key to consist of one or more fields (or segments). 


Sequenced Packet Exchange (SPX) 
A Novell communication protocol that monitors network transmission to 
ensure successful delivery. SPX runs on top of Novell's Internetwork Packet 
Exchange (IPX). 


shadow paging 
A technique that Btrieve v6.x uses to ensure data integrity. When a user needs 
to change a page, Btrieve makes the change to a physical shadow page, which 
is a virtual copy of the original page. When the change is committed, Btrieve 
designates the shadow page as the current page, and the original page becomes 
available for reuse. 


sign trailing separate (STS) 
A COBOL data type that is basically a numeric data type, represented as an 
ASCII string. STS is right justified and padded with leading zeros, and it has 
the sign byte at the end. 
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supervisor 
The person responsible for the administration and maintenance of a network, 
a database, or both. A supervisor has access rights to all volumes, directories, 
and files. 


thread 
A separate stream of execution within a program. 


transaction 
A set of related operations that constitutes a logical unit of work. The 
application performing the transaction requires that either all or none of these 
operations be performed. 


user 
Someone who is authorized to log in to a network and/or database when 
security is installed and who has access rights to specific filenames, 
directories, and files. 


Variable-tail Allocation Table (VAT) 
An array of pointers to locations within the variable-length portion of a 
Btrieve record. 
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